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

package/src/host.js

@@ -41,11 +41,10 @@ return {
     // the interpreter's absolute path and uses that instead.
     const PYTHON_CANDIDATES = opts.pythonCommand
       ? [opts.pythonCommand]
-      : (IS_WINDOWS ? ['python3', 'python'] : ['python3'])
+      : ['python3', 'python']
     // 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
+    // src/index.js. Dynamic loads use TEMP/TMPDIR or the current workspace.
+    // 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)
@@ -55,9 +54,10 @@ return {
     // 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 currentDir = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '.'
     const RUNTIME_DIR = opts.runtimeDir
       ? trimSeparator(opts.runtimeDir)
-      : (tempRoot ? trimSeparator(tempRoot) + '/.html-workbench' : '/tmp/.html-workbench')
+      : trimSeparator(tempRoot || currentDir) + '/.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
@@ -70,16 +70,24 @@ return {
     // cache/log data either way.
     const LOG_DIR = RUNTIME_DIR + '/logs'
     const VENDOR_CACHE = RUNTIME_DIR + '/vendor'
+    const hostLog = opts.hostLog || null
+    const nodeVersion = typeof process !== 'undefined' ? process.version : null
+    const arch = typeof process !== 'undefined' ? process.arch : null
+    const mode = typeof harness !== 'undefined' ? 'dynamic' : 'static'
+    let hostLogError = null
 
     // Directories the running service reported; null until it says so.
     let resolvedPaths = null
+    let serviceInfo = null
+    let startupLogFile
 
     let assets = []
     let seq = 0
     let ownedProcess = null
     let serviceRunning = false
     let startError = null
-    let pythonCommand = opts.pythonCommand || (IS_WINDOWS ? null : 'python3')
+    let pythonCommand = null
+    let dependencyIssue = null
     // 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
@@ -88,9 +96,34 @@ return {
     let pythonProbeFailedAt = 0
     let pythonProbe = null
     let disposed = false
+    let starting = null
+    let restarting = null
+    let serviceEpoch = 0
 
     const shell = ctx.get('shell')
 
+    // ── Shell API: two shapes, one contract ──────────────────────────────────
+    //
+    // The ShellExecutor that public kernels ship (`@deepseek-ai/dsh-shell`
+    // 0.1.7-rc.2 / 0.2.0-rc.2) exposes `resolve()` + `execute()` only — `run()`
+    // and `start()` were never published, so on a stock installation every call
+    // below threw (`shell.start is not a function`) and the service could never
+    // start. Both shapes are honoured: an executor offering the legacy pair is
+    // driven exactly as before, anything else goes through `execute()` —
+    // `await execute(spec).result()` IS the old `run()` (the foreground
+    // projection whose ShellRunResult/CollectedOutput fields the diagnostics
+    // below already read), and the value `execute()` resolves to IS the old
+    // `start()` handle (ShellExecution extends ShellProcess: status / exitCode /
+    // signal / readOutput() / kill()).
+    const runShell = async (spec) =>
+      typeof shell.run === 'function' ? shell.run(spec) : (await shell.execute(spec)).result()
+    const startShell = async (spec) =>
+      // `onExpiry` only in this branch: `resolve()` defaults to `'kill'` with a
+      // 60s deadline, which would kill the long-running serve process a minute
+      // after start. The legacy branch inherits whatever its executor already
+      // did with a background handle.
+      typeof shell.start === 'function' ? shell.start(spec) : shell.execute({ ...spec, onExpiry: 'none' })
+
     // ── Diagnostics journal ──────────────────────────────────────────────────
     //
     // A failed start used to surface as nothing but a red dot: the only signal
@@ -131,8 +164,10 @@ return {
     }
 
     const note = (level, message, detail) => {
-      const text = String(message || '')
-      const body = detail ? String(detail).slice(0, 4000) : null
+      const text = String(message || '').slice(0, 2000)
+      const raw = detail ? String(detail) : null
+      const body = raw && raw.length > 4000 ? raw.slice(0, 1000) + '\n…（中间输出已截断）\n' + raw.slice(-3000) : raw
+      const at = Date.now()
       // 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
@@ -144,13 +179,27 @@ return {
       }
       if (index >= 0) {
         const entry = journal.splice(index, 1)[0]
-        entry.at = Date.now()
+        entry.at = at
         entry.repeated = (entry.repeated || 1) + 1
         journal.push(entry)
       } else {
-        journal.push({ at: Date.now(), level: level, message: text, detail: body })
+        journal.push({ at, firstAt: at, level, message: text, detail: body })
         trimJournal()
       }
+      const entry = journal[journal.length - 1]
+      if (entry.loggedAt != null && at - entry.loggedAt < 60000) return
+      entry.loggedAt = at
+      if (hostLog) {
+        try {
+          hostLog.append({ at, level, message: text, detail: body, port: PORT, version: VERSION,
+            firstAt: entry.firstAt, repeated: entry.repeated || 1 })
+          hostLogError = null
+        } catch (e) {
+          const failure = (e && e.message) || String(e)
+          if (hostLogError !== failure) console.error('[html-workbench] 无法写入宿主日志', failure)
+          hostLogError = failure
+        }
+      }
       if (level === 'error') console.error('[html-workbench] ' + text, body || '')
     }
 
@@ -202,7 +251,7 @@ return {
       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 }))
+        const result = await runShell(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: 没有返回解释器路径' }
@@ -221,33 +270,41 @@ return {
       if (pythonProbeFailedAt && Date.now() - pythonProbeFailedAt < PROBE_RETRY_MS) return null
       pythonProbe = (async () => {
         const failures = []
-        for (const candidate of PYTHON_CANDIDATES) {
+        const unsupported = []
+        const checkVersion = async (command) => {
           try {
-            const spec = shell.resolve({ command: candidate + ' --version', timeoutMs: 5000, stdoutMaxBytes: 4096 })
-            const result = await shell.run(spec)
+            const spec = shell.resolve({ command: command + ' --version', timeoutMs: 5000, stdoutMaxBytes: 4096 })
+            const result = await runShell(spec)
             if (result && result.exitCode === 0) {
-              pythonCommand = candidate
-              pythonProbeFailedAt = 0
-              note('info', '使用 Python 解释器：' + candidate)
-              return pythonCommand
+              const output = outputText(result.stdout) + '\n' + outputText(result.stderr)
+              const version = /\bPython (\d+)\.(\d+)(?:\.\d+)?/.exec(output)
+              if (version && (Number(version[1]) > 3 || (version[1] === '3' && Number(version[2]) >= 9))) {
+                pythonCommand = command
+                pythonProbeFailedAt = 0
+                if (dependencyIssue?.code.startsWith('PYTHON_')) dependencyIssue = null
+                note('info', '使用 Python 解释器：' + command + '（' + version[0] + '）')
+                return true
+              }
+              if (version) unsupported.push(version[0])
             }
-            failures.push(candidate + ': ' + describeRun(result))
+            failures.push(command + ': ' + describeRun(result))
           } catch (e) {
-            failures.push(candidate + ': ' + ((e && e.message) || String(e)))
+            failures.push(command + ': ' + ((e && e.message) || String(e)))
           }
+          return false
         }
-        const launcher = await expandWindowsLauncher()
-        if (launcher && launcher.command) {
-          pythonCommand = launcher.command
-          pythonProbeFailedAt = 0
-          note('info', '使用 Python 解释器（经 py 启动器解析）：' + launcher.command)
-          return pythonCommand
+        for (const candidate of PYTHON_CANDIDATES) {
+          const command = opts.pythonCommand ? quoteArg(candidate) : candidate
+          if (await checkVersion(command)) return pythonCommand
         }
+        const launcher = await expandWindowsLauncher()
+        if (launcher?.command && await checkVersion(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 中，然后点「重启服务」。'
+        const versions = [...new Set(unsupported)].join('、')
+        startError = versions ? '检测到 ' + versions + '，版本过低。' : '找不到可用的 Python 3 解释器。'
+        startError += ' 请在运行 DSH 的电脑上安装 Python 3.9 或更高版本，确认 Python 已加入 PATH，然后重启 DSH。'
+        dependencyIssue = { code: versions ? 'PYTHON_TOO_OLD' : 'PYTHON_UNAVAILABLE', message: startError }
         note('error', startError, failures.join('\n'))
         return null
       })()
@@ -266,7 +323,7 @@ return {
       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)
+        const result = await runShell(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))
@@ -279,17 +336,17 @@ return {
 
     // `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 () => {
+    const probeHealth = async (timeoutMs = 8000) => {
       if (!shell || !SCRIPT) return null
       const python = await resolvePythonCommand()
       if (!python) return null
       try {
         const spec = shell.resolve({
           command: python + ' ' + quoteArg(SCRIPT) + ' health --port ' + PORT,
-          timeoutMs: 8000,
+          timeoutMs: timeoutMs,
           stdoutMaxBytes: 64 * 1024,
         })
-        const result = await shell.run(spec)
+        const result = await runShell(spec)
         if (!result || result.exitCode !== 0) return { ok: false, result: result }
         try {
           const payload = JSON.parse(outputText(result.stdout) || '')
@@ -309,6 +366,11 @@ return {
     // output to read them from).
     const adoptResolvedPaths = (payload) => {
       if (!payload) return
+      serviceInfo = { version: payload.version || null, pythonVersion: payload.pythonVersion || null }
+      for (const key of ['platform', 'pid', 'pythonExecutable', 'logging']) {
+        if (key in payload) serviceInfo[key] = payload[key]
+      }
+      if ('logFile' in payload) serviceInfo.logFile = payload.logFile
       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 }
@@ -326,14 +388,14 @@ return {
     // 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）。',
+      ASSET_NOT_FOUND: '缺少编辑器文件 assets/workbench.html。请重新安装 HTML Workbench 插件，然后重启 DSH。',
       PYTHON_TOO_OLD: '需要 Python 3.9 或更高版本。',
       SERVER_OUTDATED: '端口上有旧版服务且无法自动停止，请手动结束该进程。',
       FILE_NOT_FOUND: '找不到文件。',
-      VENDOR_DOWNLOAD_FAILED: '首次启动需要联网下载 GrapesJS，下载失败了。',
+      VENDOR_DOWNLOAD_FAILED: '无法准备编辑器所需的 GrapesJS。请检查运行 DSH 的电脑能否联网，以及缓存目录是否可写，然后在工作台中重启服务。',
     }
 
-    const explainOutput = (text) => {
+    const explainOutput = (text, startup = false) => {
       if (!text) return null
       for (const line of String(text).split('\n')) {
         const trimmed = line.trim()
@@ -341,8 +403,13 @@ return {
         try {
           const payload = JSON.parse(trimmed)
           if (payload && payload.ok === false && payload.error) {
+            if ('logFile' in payload) startupLogFile = payload.logFile
             const hint = CLI_HINTS[payload.error]
-            return (hint || payload.message || payload.error) + '（' + payload.error + '）'
+            const message = hint || payload.message || payload.error
+            if (startup && ['VENDOR_DOWNLOAD_FAILED', 'ASSET_NOT_FOUND'].includes(payload.error)) {
+              dependencyIssue = { code: payload.error, message }
+            }
+            return message + '（' + payload.error + '）'
           }
         } catch (e) { /* not the JSON line; keep scanning */ }
       }
@@ -365,13 +432,16 @@ return {
       }
     }
 
-    const startService = async () => {
+    const startOrReuseService = async () => {
       if (disposed) return null
+      serviceEpoch += 1
       if (serviceRunning) return health()
       const existing = await health()
+      if (disposed) return null
       if (existing) {
         serviceRunning = true
         startError = null
+        dependencyIssue = null
         healthConfirmedAt = Date.now()
         // Record the reuse too, so the journal always explains the CURRENT state
         // rather than only the failures.
@@ -381,7 +451,8 @@ return {
       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
+      if (disposed || !python) return null
+      startupLogFile = undefined
       let proc = null
       const command = python + ' ' + quoteArg(SCRIPT) + ' serve --port ' + PORT
         + ' --log-dir ' + quoteArg(LOG_DIR)
@@ -389,20 +460,29 @@ return {
         + (EDITOR_ROOT ? ' --editor-root ' + quoteArg(EDITOR_ROOT) : '')
       try {
         note('info', '启动本地服务：端口 ' + PORT, command)
-        proc = shell.start(shell.resolve({ command: command, stdoutMaxBytes: 64 * 1024 }))
+        proc = await startShell(shell.resolve({ command: command, stdoutMaxBytes: 64 * 1024 }))
         if (disposed) { try { proc.kill() } catch (e) {} return null }
         ownedProcess = proc
+        const deadline = Date.now() + 60000
         let transcript = ''
-        for (let i = 0; i < 240; i += 1) {
+        let lastProbe = null
+        while (!disposed && Date.now() < deadline) {
           const chunk = drain(proc)
-          if (chunk) transcript += (transcript ? '\n' : '') + chunk
-          const probe = await probeHealth()
-          if (probe && probe.ok) {
+          if (chunk) transcript = (transcript + '\n' + chunk).trim().slice(-16000)
+          const probe = await probeHealth(Math.max(1, Math.min(8000, deadline - Date.now())))
+          lastProbe = probe
+          if (disposed) return null
+          if (probe && probe.ok && proc.status === 'running') {
             serviceRunning = true
             startError = null
+            dependencyIssue = null
             healthConfirmedAt = Date.now()
             adoptResolvedPaths(probe.payload)
             note('info', '本地服务就绪：版本 ' + (probe.payload.version || '未知') + '，端口 ' + PORT)
+            if (probe.payload.logFile === null) {
+              const output = drain(proc)
+              note('warn', 'Python 服务未能启用文件日志', [transcript, output].filter(Boolean).join('\n'))
+            }
             return probe.payload
           }
           // Stop waiting the moment the process is gone. Polling health for the
@@ -410,29 +490,41 @@ return {
           // fast, loud failure look like a hang.
           if (proc.status !== 'running') {
             const tail = drain(proc)
-            if (tail) transcript += (transcript ? '\n' : '') + tail
+            if (tail) transcript = (transcript + '\n' + tail).trim().slice(-16000)
             // 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)
+            const explained = explainOutput(transcript, true)
+            const exit = 'serve 进程已退出（exit=' + String(proc.exitCode) + (proc.signal ? ', 信号 ' + proc.signal : '') + '）'
+            startError = explained || exit
+            note('error', startError, exit + '\n' + (transcript || '进程没有任何输出。命令：' + command))
             ownedProcess = null
             return null
           }
-          await ctx.timeout(250)
+          const remaining = deadline - Date.now()
+          if (remaining > 0) await ctx.timeout(Math.min(250, remaining))
         }
+        if (disposed) return null
         startError = '服务在 60 秒内没有就绪（端口 ' + PORT + ' 未通过健康检查）'
-        note('error', startError, transcript || '进程仍在运行但健康检查一直失败。命令：' + command)
+        const probeDetail = lastProbe && (lastProbe.error || describeRun(lastProbe.result))
+        note('error', startError, [transcript, probeDetail && '最后一次健康检查：' + probeDetail, command].filter(Boolean).join('\n'))
+        // The public executor leaves serve running until we stop it.
+        proc.kill()
+        ownedProcess = null
         return null
       } catch (e) {
         startError = 'serve 进程启动失败：' + ((e && e.message) || String(e))
-        note('error', startError, command)
+        note('error', startError, [e && e.stack, command].filter(Boolean).join('\n'))
         if (proc) { try { proc.kill() } catch (e2) {} }
         ownedProcess = null
         return null
       }
     }
 
+    const startService = () => {
+      if (!starting) starting = startOrReuseService().finally(() => { starting = null })
+      return starting
+    }
+
     // 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
@@ -440,34 +532,40 @@ return {
     // existing poll can supervise the process for free.
     const superviseOwnedProcess = () => {
       const proc = ownedProcess
-      if (!proc || proc.status === 'running') return
+      if (starting || !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 || '进程没有留下输出。可用「重启服务」重新拉起。')
+      note('error', '服务进程意外退出', [startError, tail || '进程没有留下输出。'].join('\n'))
     }
 
-    // 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.
+    // Periodically refresh health and log-write status for both owned and reused
+    // services. A live process handle alone cannot tell whether logging failed.
     const REVALIDATE_MS = 10000
     let healthConfirmedAt = 0
     let revalidating = false
 
     const revalidateService = () => {
-      if (revalidating || ownedProcess || !serviceRunning) return
+      if (disposed || starting || restarting || revalidating || !serviceRunning) return
       if (Date.now() - healthConfirmedAt < REVALIDATE_MS) return
+      const epoch = serviceEpoch
       revalidating = true
       void (async () => {
         try {
-          if (await health()) { healthConfirmedAt = Date.now(); return }
+          const probe = await probeHealth()
+          // A delayed probe belongs to the service it checked, even if a restart
+          // has already finished. Never replace the new process's diagnostics.
+          if (disposed || epoch !== serviceEpoch) return
+          if (probe && probe.ok) {
+            adoptResolvedPaths(probe.payload)
+            healthConfirmedAt = Date.now()
+            return
+          }
           serviceRunning = false
-          startError = '之前复用的服务已经不再响应（端口 ' + PORT + '）。'
-          note('error', '复用的服务失去响应', '健康检查失败。可用「重启服务」重新拉起。')
+          startError = '本地服务已经不再响应（端口 ' + PORT + '）。'
+          note('error', '本地服务失去响应', probe && (probe.error || describeRun(probe.result)))
         } finally {
           revalidating = false
         }
@@ -477,42 +575,54 @@ return {
     // 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 diagnosticFacts = () => ({
+      version: VERSION,
+      mode,
+      platform: PLATFORM,
+      arch,
+      nodeVersion,
+      shellAPI: shell ? ['resolve', 'execute', 'run', 'start'].filter(name => typeof shell[name] === 'function') : [],
+      port: PORT,
+      script: SCRIPT,
+      editorRoot: EDITOR_ROOT,
+      runtimeDir: RUNTIME_DIR,
+      pythonCommand,
+      pythonCandidates: PYTHON_CANDIDATES.slice(),
+      logDir: (resolvedPaths && resolvedPaths.logDir) || LOG_DIR,
+      vendorCache: (resolvedPaths && resolvedPaths.vendorCache) || VENDOR_CACHE,
+      hostLogFile: hostLog ? hostLog.file : null,
+      hostLogError,
+      service: serviceInfo,
+      startupLogFile,
+      hasShell: !!shell,
+      startError,
+      dependencyIssue,
+      journal: journal.slice().reverse(),
+    })
+
     const diagnostics = () => {
       superviseOwnedProcess()
       revalidateService()
       return {
+        ...diagnosticFacts(),
         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
+      serviceEpoch += 1
       const proc = ownedProcess
       ownedProcess = null
       serviceRunning = false
-      if (proc) { try { proc.kill() } catch (e) { console.error('[html-workbench] stop failed', e) } }
+      if (proc) {
+        try { proc.kill() } catch (e) { note('error', '卸载插件时无法停止服务', e.stack || e) }
+      }
     })
 
     const recordAsset = (path, kind) => {
@@ -537,7 +647,7 @@ return {
         if (!/\.html?$/i.test(path)) return
         recordAsset(path, exec.name === 'write' ? 'create' : 'edit')
       } catch (e) {
-        console.error('[html-workbench] track failed', e)
+        note('error', '记录 HTML 产物时出错', e.stack || e)
       }
     })
 
@@ -547,12 +657,18 @@ return {
       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()
+      const wasUp = !starting && !restarting ? await health() : null
+      const h = restarting ? (await restarting).info : wasUp || await startService()
       // 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() }
+      if (!h) {
+        note('error', '打开编辑器时健康检查失败', startError)
+        return { ok: false, error: startError || '本地服务未就绪', diagnostics: diagnostics() }
+      }
+      adoptResolvedPaths(h)
+      serviceRunning = true
+      startError = null
+      healthConfirmedAt = Date.now()
       return {
         ok: true,
         url: 'http://127.0.0.1:' + PORT + '/?file=' + encodeURIComponent(file),
@@ -562,12 +678,19 @@ return {
       }
     }
 
-    const restartService = async () => {
+    const stopAndRestartService = async () => {
+      serviceEpoch += 1
+      await starting
+      if (disposed) return { ok: false, error: 'HTML Workbench 已卸载' }
       const proc = ownedProcess
       ownedProcess = null
       serviceRunning = false
       startError = null
-      if (proc) { try { proc.kill() } catch (e) {} }
+      if (dependencyIssue?.code.startsWith('PYTHON_')) pythonProbeFailedAt = 0
+      dependencyIssue = null
+      if (proc) {
+        try { proc.kill() } catch (e) { note('error', '重启前无法停止服务进程', e.stack || 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
@@ -581,6 +704,18 @@ return {
       return h ? { ok: true, info: h, diagnostics: diagnostics() } : { ok: false, error: startError || '重启失败', diagnostics: diagnostics() }
     }
 
+    const restartService = () => {
+      if (!restarting) restarting = stopAndRestartService().finally(() => { restarting = null })
+      return restarting
+    }
+
+    const dependencyPayload = async () => {
+      const pending = restarting || starting
+      if (pending) await pending
+      else if (!serviceRunning && !startError) await startService()
+      return { ok: true, dependencyIssue }
+    }
+
     // 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.
@@ -591,9 +726,8 @@ return {
         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
+        if (IS_WINDOWS && /^[\\/][A-Za-z]:\//.test(path)) path = path.slice(1)
+        if (IS_WINDOWS && url.hostname && url.hostname !== 'localhost') path = '//' + url.hostname + path
         return path
       } catch (e) {
         return raw
@@ -614,15 +748,20 @@ return {
         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), normalized: normalized }
+        const spec = shell.resolve({
+          command: python + ' -c ' + quoteArg(probe) + ' ' + quoteArg(normalized),
+          timeoutMs: 5000,
+          stdoutMaxBytes: 1024,
+        })
+        const r = await runShell(spec)
+        if (r && !r.timedOut && !r.aborted && !r.signal && [0, 1].includes(r.exitCode)) {
+          return { ok: true, isHtml: true, exists: r.exitCode === 0, normalized: normalized }
+        }
+        note('error', '文件检查未完成', describeRun(r))
+        return { ok: true, isHtml: true, exists: null, normalized, error: '文件检查未完成，请查看诊断日志。' }
       } catch (e) {
+        note('error', '文件检查未完成', e.stack || e)
         return { ok: true, isHtml: true, exists: null, normalized: normalized, error: (e && e.message) || String(e) }
       }
     }
@@ -651,28 +790,32 @@ return {
         return diagnostics()
       } catch (error) {
         return {
+          ...diagnosticFacts(),
           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', () => 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())
+      const handle = (name, handler) => harness.handle(name, async (args) => {
+        try {
+          return await handler(args)
+        } catch (error) {
+          const reason = (error && error.stack) || String(error)
+          note('error', 'RPC ' + name + ' 处理失败', reason)
+          return { ok: false, error: (error && error.message) || String(error), diagnostics: safeDiagnostics() }
+        }
+      })
+      handle('list', listPayload)
+      handle('status', statusPayload)
+      handle('open', (args) => openFile(args && args.file))
+      handle('resolve', (args) => resolvePath(args && args.file))
+      handle('diagnostics', safeDiagnostics)
+      handle('dependencies', dependencyPayload)
+      handle('restart', restartService)
     }
 
     // 静态传输：HTTP 路由，供静态 client bundle（fetch）与直接浏览器访问使用。
@@ -727,6 +870,11 @@ return {
         path: '/html-workbench/list',
         handler: guard('list', (req, res) => sendJson(res, 200, listPayload())),
       }), 'html-workbench: list route')
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/html-workbench/dependencies',
+        handler: guard('dependencies', async (req, res) => sendJson(res, 200, await dependencyPayload())),
+      }), 'html-workbench: dependencies route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/status',
@@ -763,7 +911,8 @@ return {
     // 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) => {
+    note('info', '插件宿主已加载', JSON.stringify({ mode, platform: PLATFORM, arch, nodeVersion, script: SCRIPT, runtimeDir: RUNTIME_DIR }))
+    Promise.resolve().then(() => restarting ? null : startService()).catch((error) => {
       startError = '启动本地服务时发生未预期的错误：' + ((error && error.message) || String(error))
       note('error', startError, (error && error.stack) || null)
     })