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

package/README.md

@@ -28,15 +28,29 @@ dsh-plugin/
 
 `host.js` 默认用本机仓库内的 `skill/html-workbench/scripts/workbench.py` 拉起服务。
 
-### 静态装载（后续发布 NPM 时再接入）
+### 静态装载（已发布 NPM）
 
-`cordis.patch.yml` + `package.json` 的 `dsh.bundle` 已就绪；Client 半的静态 bundle（`window.__ModuleLoader__.load`）尚未接入，动态 Client 已可用。
+`cordis.patch.yml` + `package.json` 的 `dsh.bundle` 把插件作为一层 profile 装载；Client 半由 `npm run build` 打成 `lib/client.js`（`window.__ModuleLoader__.load`）。`prepublishOnly` 会自动构建，所以 `lib/`、`scripts/`、`assets/` 是构建产物、不入库。
 
 ## 服务生命周期（副作用管理）
 
 - **注册时**：`apply` 里异步 `startService()`，先 `health` 探测 `4317`；已在运行则复用（不认领），否则 `shell.start` 后台拉起 `workbench.py serve`。
 - **卸载时**：`ctx.effect` 的 disposer `kill()` 掉本插件自己启动的那个进程；复用的服务不误杀。
 
+## 运行时目录（Windows 沙箱）
+
+服务日志与 GrapesJS 缓存写在 `<工作区>/.html-workbench/`（常量 `RUNTIME_DIR_NAME`，Host 与 `workbench.py` 必须一致）。
+
+这些路径是**请求，不是保证**：服务是 DSH 的沙箱子进程，只能写会话工作区和沙箱交给它的私有临时目录，**系统 `%TEMP%` 根一律拒绝**——即使父进程能建出那个文件夹，子进程也写不进去。因此：
+
+- `workbench.py` 在**自身进程内**用一次真实创建探测候选目录，被拒就立刻换下一个（工作区 → 私有临时目录），并把**实际使用**的目录写进 `/api/health` 的 `logDir` / `vendorCache`；
+- Host 采纳上报值（`adoptResolvedPaths`），于是面板显示的是真实路径，而不是它请求过的路径；复用别的进程启动的服务时同样如此；
+- 探测**不允许重试**：Windows 上 `tempfile.mkstemp` 遇到 `PermissionError` 会用只看 DACL 的 `os.access` 复检、再换随机名重试 10 000 次，会把"1 秒报错"变成"卡住数分钟并烧 CPU"。故改用 `make_temp_file()` 的单次 `O_EXCL` 打开。
+
+日志目录**全部候选都不可写**时，服务挂 `NullHandler` 照常启动：丢一份诊断日志可以接受，端口不 bind 不可以。
+
+工作区通常就是**用户自己的仓库**，所以建出目录的那一半会在运行时根写入内容为 `*` 的 `.gitignore`（`self_ignore()` / `probeWritableDir()`），让整棵树连同该文件一起对 git 隐形——本仓库的 `.gitignore` 只管得住自己的 checkout。判定依据是 `RUNTIME_DIR_NAME` 而非传入目录，否则 `--log-dir .` 会把用户的源码树整个变成被忽略的。
+
 ## RPC 接口（Client → Host）
 
 | method   | 入参        | 返回                                   |

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "@vibe-x/dsh-html-workbench",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "main": "./src/index.js",
   "description": "在 DeepSeek Harness 右侧栏预览并可视化编辑 agent 生成的 HTML：复用/拉起本地 html-workbench 服务，在 iframe 中内嵌 GrapesJS 编辑器，插件卸载时停掉自己启动的服务。",
   "engines": {

package/lib/client.js

@@ -49,6 +49,20 @@ window.__ModuleLoader__.load({
           } catch (error) {
             throw new Error('本地服务返回了无法解析的 JSON（HTTP ' + response.status + '）。');
           }
+        }, (error) => {
+          // fetch REJECTS (rather than resolving with a status) when the request
+          // never reached DSH's web server. Left alone, the browser's bare
+          // "Failed to fetch" surfaced in the panel — the single least actionable
+          // string in this plugin, and the one users reported. It also means the
+          // host half never ran, so none of its diagnostics exist yet: the only
+          // useful thing to report is WHICH request died and what to check.
+          const reason = (error && error.message) || String(error);
+          throw new Error(
+            '无法连接 HTML Workbench 后台（' + method + '）。请求 ' + url + ' 没有到达 DSH。'
+            + '通常说明插件的 Node 半没有加载成功，或 DSH 尚未重启以注册该路由。'
+            + '请完全重启 DSH；若仍失败，请在启动 DSH 的终端里查找 [html-workbench] 开头的报错。'
+            + '（底层错误：' + reason + '）'
+          );
         });
       },
     };
@@ -154,6 +168,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
 .hwb-diag-row + .hwb-diag-row { border-top: 1px solid color-mix(in srgb, var(--dsw-alias-border-l2) 50%, transparent); }
 .hwb-diag-time { color: var(--dsw-alias-label-tertiary); font-family: var(--hwb-mono); font-size: 10.5px; padding-top: 1px; }
 .hwb-diag-msg { min-width: 0; }
+.hwb-diag-count { margin-left: 6px; padding: 0 5px; border-radius: 999px; background: var(--dsw-alias-bg-base); color: var(--dsw-alias-label-tertiary); font-family: var(--hwb-mono); font-size: 10px; }
 .hwb-diag-row[data-level="error"] .hwb-diag-msg { color: var(--dsw-alias-state-error-primary); }
 .hwb-diag-detail { display: block; margin-top: 3px; padding: 6px 8px; border-radius: 6px; background: var(--dsw-alias-bg-base); color: var(--dsw-alias-label-secondary); font-family: var(--hwb-mono); font-size: 10.5px; line-height: 1.5; white-space: pre-wrap; word-break: break-word; max-height: 180px; overflow-y: auto; }
 .hwb-diag-empty { padding: 16px 14px; color: var(--dsw-alias-label-tertiary); font-size: 11.5px; }
@@ -676,8 +691,12 @@ header:has([data-slot="conversation.session.header.utilities"]) {
           if (!res.isHtml) store.set({ resolveState: 'invalid' })
           else if (res.exists === true) store.set({ resolveState: 'exists' })
           else if (res.exists === false) store.set({ resolveState: 'missing' })
+          // `exists: null` means the CHECK could not run (no interpreter, no
+          // shell). Staying silent made the field look unresponsive, so promote
+          // the host's reason to the banner instead of dropping it.
+          else if (res.error) store.set({ resolveState: 'idle', error: res.error })
           else store.set({ resolveState: 'idle' })
-        }).catch(() => store.set({ resolveState: 'idle' }))
+        }).catch((e) => store.set({ resolveState: 'idle', error: String(e && e.message ? e.message : e) }))
       }, 300)
     }
 
@@ -730,6 +749,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
       const s = useStore()
       const d = s.diag
       const journal = (d && d.journal) || []
+      const [copied, setCopied] = React.useState(false)
 
       const fact = (key, value) => value == null || value === ''
         ? null
@@ -738,10 +758,53 @@ header:has([data-slot="conversation.session.header.utilities"]) {
           React.createElement('span', { className: 'hwb-diag-val', key: key + '-v' }, String(value)),
         ]
 
+      // A bug report is only useful if it carries the journal. Asking a user to
+      // screenshot a scrolling panel loses exactly the detail lines that matter,
+      // so hand them one paste-ready block instead — plain text, not JSON, so it
+      // survives being dropped into a chat window.
+      const copyReport = () => {
+        const lines = ['# HTML Workbench 诊断报告']
+        if (d) {
+          lines.push('插件版本: ' + (d.version || '未知（可能是动态热加载）'))
+          lines.push('平台: ' + (d.platform || '未知'))
+          lines.push('状态: ' + (d.running ? '运行中' : '未就绪'))
+          lines.push('端口: ' + d.port)
+          lines.push('进程: ' + (d.processStatus || '未由本插件启动')
+            + (d.exitCode == null ? '' : '（exit=' + d.exitCode + '）'))
+          lines.push('Python: ' + (d.pythonCommand || (d.pythonCandidates || []).join(' → ') || '未解析'))
+          lines.push('脚本: ' + (d.script || '未配置'))
+          lines.push('运行目录: ' + (d.runtimeDir || '未知'))
+          if (d.startError) lines.push('失败原因: ' + d.startError)
+        } else {
+          lines.push('（后台未返回诊断信息，通常说明请求根本没有到达 DSH）')
+        }
+        if (s.error) lines.push('界面报错: ' + s.error)
+        lines.push('', '## 日志（最新在前）')
+        if (journal.length) {
+          journal.forEach((entry) => {
+            lines.push('[' + clockTime(entry.at) + '] ' + entry.level + ': ' + entry.message)
+            if (entry.detail) lines.push('    ' + String(entry.detail).replace(/\n/g, '\n    '))
+          })
+        } else {
+          lines.push('（无）')
+        }
+        const text = lines.join('\n')
+        const done = () => { setCopied(true); setTimeout(() => setCopied(false), 1600) }
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).then(done, () => store.set({ error: '复制失败，请手动访问 /html-workbench/diagnostics 获取原始信息。' }))
+        } else {
+          store.set({ error: '当前环境不支持剪贴板，请访问 /html-workbench/diagnostics 获取原始信息。' })
+        }
+      }
+
       return React.createElement('div', { className: 'hwb-diag' },
         React.createElement('div', { className: 'hwb-diag-head' },
           React.createElement('span', { className: 'hwb-diag-title' }, '服务诊断'),
           React.createElement('span', { className: 'hwb-spacer' }),
+          React.createElement('button', {
+            type: 'button', className: 'hwb-btn hwb-btn-quiet hwb-btn-sm',
+            onClick: copyReport, title: '复制完整诊断信息，便于反馈问题',
+          }, copied ? '已复制' : '复制报告'),
           React.createElement('button', {
             type: 'button', className: 'hwb-btn hwb-btn-quiet hwb-btn-sm',
             disabled: s.restarting, onClick: restartService,
@@ -756,8 +819,11 @@ header:has([data-slot="conversation.session.header.utilities"]) {
             fact('状态', d.running ? '运行中' : (d.processStatus === 'running' ? '启动中' : '未就绪')),
             fact('端口', d.port),
             fact('进程', d.processStatus ? d.processStatus + (d.exitCode == null ? '' : '（exit=' + d.exitCode + '）') : '未由本插件启动'),
+            fact('Python', d.pythonCommand || ((d.pythonCandidates || []).join(' → ') || null)),
+            fact('运行目录', d.runtimeDir),
             fact('失败原因', d.startError),
             fact('脚本', d.script),
+            fact('版本', d.version ? d.version + (d.platform ? ' · ' + d.platform : '') : d.platform),
             d.hasShell === false ? fact('shell', '不可用') : null,
           )
           : null,
@@ -769,6 +835,11 @@ header:has([data-slot="conversation.session.header.utilities"]) {
               React.createElement('span', { className: 'hwb-diag-time' }, clockTime(entry.at)),
               React.createElement('span', { className: 'hwb-diag-msg' },
                 entry.message,
+                // Folded duplicates would otherwise read as a single occurrence,
+                // hiding that the user retried and hit the same wall every time.
+                entry.repeated > 1
+                  ? React.createElement('span', { className: 'hwb-diag-count' }, '×' + entry.repeated)
+                  : null,
                 entry.detail ? React.createElement('span', { className: 'hwb-diag-detail' }, entry.detail) : null,
               ),
             ))
@@ -776,7 +847,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
         ),
         React.createElement('div', { className: 'hwb-diag-hint' },
           '服务自身日志：',
-          React.createElement('code', null, (d && d.logDir) || '/tmp/html-workbench-dsh/logs/'),
+          React.createElement('code', null, (d && d.logDir) || '<工作区>/.html-workbench/logs/'),
           '；也可直接访问 ',
           React.createElement('code', null, '/html-workbench/diagnostics'),
           ' 查看原始 JSON。',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-x/dsh-html-workbench",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DeepSeek Harness 插件：在右侧栏预览并可视化编辑 agent 生成的 HTML（复用/拉起本地 html-workbench 服务）。",
   "license": "MIT",
   "type": "module",

package/scripts/workbench.py

@@ -34,7 +34,7 @@ from typing import Any
 
 
 SERVICE_NAME = "html-workbench"
-SERVICE_VERSION = "2.1.0"
+SERVICE_VERSION = "2.2.0"
 
 DEFAULT_PORT = 4317
 # Capability names advertised by /api/health. `command_open` refuses to reuse a
@@ -126,6 +126,135 @@ def default_log_dir() -> Path:
     return base / "html-workbench" / "logs"
 
 
+# Name of the runtime-state folder this process keeps beside its working
+# directory. The DSH plugin resolves the same name host-side, so both halves
+# agree on one location instead of scattering `.html-workbench` and
+# `html-workbench-dsh` through the user's workspace.
+RUNTIME_DIR_NAME = ".html-workbench"
+
+
+def runtime_directory() -> Path:
+    """Return this process's runtime-state root: `<cwd>/<RUNTIME_DIR_NAME>`.
+
+    Under DSH the working directory is the session workspace, which is one of the
+    only two trees the subprocess sandbox grants write access to — the other is a
+    private temp directory it hands the child through TEMP/TMP. Everywhere else
+    the working directory is simply a sensible, self-cleaning location. Logs and
+    the GrapesJS cache are disposable, so either is acceptable; what is NOT
+    acceptable is a path the sandbox refuses (see `pick_writable_dir`).
+    """
+    return Path.cwd() / RUNTIME_DIR_NAME
+
+
+def make_temp_file(directory: Path, prefix: str, suffix: str = "") -> tuple[int, Path]:
+    """Create a uniquely named temporary file in `directory`; return (fd, path).
+
+    Deliberately NOT `tempfile.mkstemp`. On Windows CPython's `_mkstemp_inner`
+    treats a `PermissionError` as "that name is already taken": it re-checks the
+    directory with `os.access(dir, os.W_OK)` and then retries with a NEW random
+    name, up to TMP_MAX (10 000) times. A real DACL always looks writable to
+    `os.access`, which cannot see the restricted token DSH's sandbox runs the
+    child under — so a directory the sandbox refuses makes `mkstemp` spin for
+    minutes (one denied `os.open` per iteration, ~4 ms each) instead of failing
+    in milliseconds. A single O_EXCL open turns that into an immediate error the
+    caller can catch and recover from.
+    """
+    for attempt in range(64):
+        candidate = Path(directory) / f"{prefix}{os.getpid()}-{attempt}-{os.urandom(6).hex()}{suffix}"
+        try:
+            descriptor = os.open(
+                candidate,
+                os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0),
+                0o600,
+            )
+        except FileExistsError:
+            continue
+        return descriptor, candidate
+    raise FileExistsError(f"无法在 {directory} 创建临时文件：连续的文件名冲突")
+
+
+def self_ignore(directory: Path) -> None:
+    """Make a runtime directory invisible to git, best effort.
+
+    The runtime root usually lands inside the session workspace, which for most
+    users is a repository: without this, every start dirties `git status` with a
+    folder holding nothing but logs and a re-downloadable cache, and the noise
+    lands in the user's own project rather than ours. A `.gitignore` containing
+    `*` excludes the tree including that file, so nothing has to be added to the
+    repository's own ignore rules.
+
+    Only the runtime root is marked — never an arbitrary directory the caller
+    happened to pass, which may be the user's source tree (`--log-dir .`).
+    """
+    root = next((parent for parent in (directory, *directory.parents) if parent.name == RUNTIME_DIR_NAME), None)
+    if root is None:
+        return
+    marker = root / ".gitignore"
+    if marker.exists():
+        return
+    try:
+        marker.write_text("# Created by html-workbench: disposable logs and cache.\n*\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def pick_writable_dir(*candidates: Path) -> Path:
+    """Return the first candidate directory this process can really write into.
+
+    Existence proves nothing: the sandbox DACL looks writable on paper while the
+    restricted token is denied, and a folder the unconfined parent created may
+    reject every file creation here with EACCES / WinError 5. The only reliable
+    test is an actual create, which `make_temp_file` performs and fails fast.
+    Falls back to the first candidate so a caller with nothing writable at all
+    still gets a deterministic path (and a clear error at the real write).
+    """
+    fallback: Path | None = None
+    for candidate in candidates:
+        if candidate is None:
+            continue
+        if fallback is None:
+            fallback = candidate
+        try:
+            candidate.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            continue
+        try:
+            descriptor, probe = make_temp_file(candidate, prefix=".wb-write-probe.")
+        except OSError:
+            continue
+        os.close(descriptor)
+        try:
+            probe.unlink()
+        except OSError:
+            pass
+        self_ignore(candidate)
+        return candidate
+    return fallback if fallback is not None else Path.cwd()
+
+
+def log_candidates(log_dir: Path | str) -> tuple[Path, ...]:
+    """Log directories to try, best first: the caller's, then writable fallbacks."""
+    return (
+        Path(log_dir).expanduser(),
+        runtime_directory() / "logs",
+        Path(tempfile.gettempdir()) / RUNTIME_DIR_NAME / "logs",
+    )
+
+
+def vendor_candidates(vendor_cache: Path | str, log_dir: Path) -> tuple[Path, ...]:
+    """Vendor-cache directories to try, best first.
+
+    The cache sits beside whichever directory accepted the log: both are
+    re-creatable, and the log's parent already proved it is writable.
+    """
+    return (
+        Path(vendor_cache).expanduser(),
+        Path(log_dir).parent / "vendor",
+        runtime_directory() / "vendor",
+        Path(tempfile.gettempdir()) / RUNTIME_DIR_NAME / "vendor",
+    )
+
+
 _logger: logging.Logger | None = None
 
 
@@ -144,27 +273,40 @@ def get_logger() -> logging.Logger:
     return _logger
 
 
-def setup_logging(log_dir: Path | str, port: int | None = None) -> logging.Logger:
-    """Attach the rotating file handler and return the module logger."""
+def setup_logging(log_dir: Path | str, port: int | None = None) -> tuple[logging.Logger, Path]:
+    """Attach the rotating file handler; return the logger and the directory used.
+
+    The requested `--log-dir` can be unusable even when it already exists — the
+    sandbox denies writes to a folder whose DACL looks writable (see
+    `pick_writable_dir`). The directory is therefore probed and handed back to
+    the caller, so the host can report where the log really is instead of echoing
+    the path it merely asked for. A missing service log is never worth failing
+    the whole start: when EVERY candidate refuses writes, `pick_writable_dir`
+    returns a deterministic path that the handler cannot open, so the failure is
+    swallowed and the service runs without a file log rather than never binding
+    its port.
+    """
     global _logger
-    directory = Path(log_dir).expanduser()
-    directory.mkdir(parents=True, exist_ok=True)
+    directory = pick_writable_dir(*log_candidates(log_dir))
     filename = f"workbench-{port}.log" if port is not None else "workbench.log"
-    handler = RotatingFileHandler(
-        directory / filename,
-        maxBytes=LOG_MAX_BYTES,
-        backupCount=LOG_BACKUP_COUNT,
-        encoding="utf-8",
-    )
-    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
     logger = get_logger()
     for existing in list(logger.handlers):
         if isinstance(existing, RotatingFileHandler):
             existing.close()
             logger.removeHandler(existing)
-    logger.addHandler(handler)
     logger.setLevel(logging.INFO)
-    return logger
+    try:
+        handler = RotatingFileHandler(
+            directory / filename,
+            maxBytes=LOG_MAX_BYTES,
+            backupCount=LOG_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+    except OSError:
+        return logger, directory
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    logger.addHandler(handler)
+    return logger, directory
 
 
 def sha256_bytes(content: bytes) -> str:
@@ -218,7 +360,7 @@ def vendor_from_cdn(base_url: str) -> dict[str, bytes]:
 def write_vendor_cache(cache_dir: Path, files: dict[str, bytes]) -> None:
     cache_dir.mkdir(parents=True, exist_ok=True)
     for name, content in files.items():
-        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{name}.", dir=cache_dir)
+        descriptor, temporary_name = make_temp_file(cache_dir, prefix=f".{name}.")
         try:
             with os.fdopen(descriptor, "wb") as output:
                 output.write(content)
@@ -982,9 +1124,9 @@ def promote_identities(target: Path, descriptors: list[dict[str, Any]], base_rev
 
 
 def write_atomic(target: Path, content: str) -> None:
-    temporary_name: str | None = None
+    temporary_name: Path | None = None
     try:
-        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.workbench-", suffix=".tmp", dir=target.parent)
+        descriptor, temporary_name = make_temp_file(target.parent, prefix=f".{target.name}.workbench-", suffix=".tmp")
         with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as output:
             output.write(content)
             output.flush()
@@ -1231,7 +1373,7 @@ def save_document(target: Path, body: dict[str, Any]) -> dict[str, Any]:
     if latest["revision"] != base_revision:
         raise WorkbenchError("REVISION_CONFLICT", "保存期间文件发生外部修改，未覆盖最新版。", 409, document=latest)
 
-    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.workbench-", suffix=".tmp", dir=target.parent)
+    descriptor, temporary_name = make_temp_file(target.parent, prefix=f".{target.name}.workbench-", suffix=".tmp")
     try:
         with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as output:
             output.write(source)
@@ -1249,11 +1391,24 @@ class WorkbenchServer(ThreadingHTTPServer):
     daemon_threads = True
     allow_reuse_address = True
 
-    def __init__(self, address: tuple[str, int], asset_file: Path, editor_root: Path, vendor_files: dict[str, Path]) -> None:
+    def __init__(
+        self,
+        address: tuple[str, int],
+        asset_file: Path,
+        editor_root: Path,
+        vendor_files: dict[str, Path],
+        log_dir: Path | None = None,
+        vendor_cache: Path | None = None,
+    ) -> None:
         self.asset_file = asset_file.resolve(strict=True)
         self.editor_root = editor_root.resolve(strict=True)
         self.vendor_files = {name: path.resolve(strict=True) for name, path in vendor_files.items()}
         self.vendor_routes = {str(metadata["route"]): name for name, metadata in VENDOR_ASSETS.items()}
+        # Advertised by /api/health so the host can report the directories actually
+        # in use — including when it REUSES a service it did not start and has no
+        # startup output to read them from.
+        self.log_dir = Path(log_dir) if log_dir is not None else None
+        self.vendor_cache = Path(vendor_cache) if vendor_cache is not None else None
         super().__init__(address, WorkbenchHandler)
 
 
@@ -1300,14 +1455,23 @@ class WorkbenchHandler(BaseHTTPRequestHandler):
         query = urllib.parse.parse_qs(parsed.query)
         try:
             if parsed.path == "/api/health":
-                self.send_json(200, {
+                payload: dict[str, Any] = {
                     "ok": True,
                     "service": SERVICE_NAME,
                     "version": SERVICE_VERSION,
                     "port": self.server.server_port,
                     "editorRoot": str(self.server.editor_root),
                     "capabilities": list(SERVICE_CAPABILITIES),
-                })
+                }
+                # Report where this process really writes. The host shows these in
+                # its diagnostics, so a REUSED service describes its own
+                # directories instead of the ones the caller asked for — which may
+                # be exactly what the sandbox refused.
+                if self.server.log_dir is not None:
+                    payload["logDir"] = str(self.server.log_dir)
+                if self.server.vendor_cache is not None:
+                    payload["vendorCache"] = str(self.server.vendor_cache)
+                self.send_json(200, payload)
                 return
             if parsed.path == "/api/document":
                 self.send_json(200, read_document(self.query_file(query)))
@@ -1536,10 +1700,15 @@ def terminate_process(pid: int) -> None:
         pass
 
 
-def start_detached(script_file: Path, port: int, editor_root: Path, asset_file: Path | None, vendor_cache: Path, log_dir: Path) -> tuple[int, Path]:
-    directory = Path(log_dir).expanduser()
-    directory.mkdir(parents=True, exist_ok=True)
-    log_file = directory / f"html-workbench-{port}.log"
+def start_detached(script_file: Path, port: int, editor_root: Path, asset_file: Path | None, vendor_cache: Path, log_dir: Path) -> tuple[int, Path | None]:
+    """Spawn a detached `serve` and return (pid, path of its captured output).
+
+    The path is None when no candidate directory accepted the file: a service
+    whose console output cannot be captured must still start, so the output is
+    discarded rather than the spawn abandoned (see `setup_logging`).
+    """
+    directory = pick_writable_dir(*log_candidates(log_dir))
+    log_file: Path | None = directory / f"html-workbench-{port}.log"
     command = [sys.executable, str(script_file), "serve", "--port", str(port), "--editor-root", str(editor_root), "--vendor-cache", str(vendor_cache), "--log-dir", str(directory)]
     if asset_file is not None:
         command.extend(["--asset", str(asset_file)])
@@ -1549,19 +1718,45 @@ def start_detached(script_file: Path, port: int, editor_root: Path, asset_file:
         flags = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS  # type: ignore[attr-defined]
         kwargs["creationflags"] = flags
         kwargs.pop("start_new_session", None)
-    with log_file.open("ab") as log:
-        process = subprocess.Popen(command, stdout=log, stderr=subprocess.STDOUT, close_fds=True, **kwargs)
+    try:
+        log = log_file.open("ab")
+    except OSError:
+        log_file = None
+        log = None
+    try:
+        process = subprocess.Popen(
+            command,
+            stdout=log if log is not None else subprocess.DEVNULL,
+            stderr=subprocess.STDOUT,
+            close_fds=True,
+            **kwargs,
+        )
+    finally:
+        if log is not None:
+            log.close()
     return process.pid, log_file
 
 
 def command_serve(args: argparse.Namespace, script_file: Path) -> int:
-    logger = setup_logging(args.log_dir, args.port)
+    logger, log_directory = setup_logging(args.log_dir, args.port)
     asset_file = Path(args.asset).expanduser().resolve(strict=True) if args.asset else default_asset_file(script_file)
     editor_root = Path(args.editor_root).expanduser().resolve(strict=True)
-    vendor_files = ensure_vendor_assets(Path(args.vendor_cache).expanduser())
-    server = WorkbenchServer(("127.0.0.1", args.port), asset_file, editor_root, vendor_files)
-    logger.info("service started: port=%s editorRoot=%s logDir=%s", args.port, editor_root, Path(args.log_dir).expanduser())
-    print(json.dumps({"ok": True, "url": f"http://127.0.0.1:{args.port}", "editorRoot": str(editor_root)}, ensure_ascii=False), flush=True)
+    # Logs and cache are both disposable, so they follow the writable location the
+    # sandbox really granted instead of the path the parent requested.
+    vendor_cache = pick_writable_dir(*vendor_candidates(args.vendor_cache, log_directory))
+    vendor_files = ensure_vendor_assets(vendor_cache)
+    server = WorkbenchServer(("127.0.0.1", args.port), asset_file, editor_root, vendor_files, log_directory, vendor_cache)
+    logger.info("service started: port=%s editorRoot=%s logDir=%s vendorCache=%s", args.port, editor_root, log_directory, vendor_cache)
+    # The host surfaces these two paths in its diagnostics, so the panel shows the
+    # directories actually in use rather than echoing the ones it asked for — the
+    # requested ones may be exactly what the sandbox refused.
+    print(json.dumps({
+        "ok": True,
+        "url": f"http://127.0.0.1:{args.port}",
+        "editorRoot": str(editor_root),
+        "logDir": str(log_directory),
+        "vendorCache": str(vendor_cache),
+    }, ensure_ascii=False), flush=True)
     try:
         server.serve_forever(poll_interval=0.25)
     except KeyboardInterrupt:
@@ -1600,7 +1795,8 @@ def command_open(args: argparse.Namespace, script_file: Path) -> int:
                 break
             time.sleep(0.1)
         else:
-            raise WorkbenchError("SERVER_UNAVAILABLE", f"服务启动失败，请查看日志：{log_file}", 500)
+            where = f"，请查看日志：{log_file}" if log_file is not None else "（没有可写的日志目录，输出已丢弃）"
+            raise WorkbenchError("SERVER_UNAVAILABLE", f"服务启动失败{where}", 500)
     query = urllib.parse.urlencode({"file": str(target)})
     print(json.dumps({
         "ok": True,

package/src/client.js

@@ -98,6 +98,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
 .hwb-diag-row + .hwb-diag-row { border-top: 1px solid color-mix(in srgb, var(--dsw-alias-border-l2) 50%, transparent); }
 .hwb-diag-time { color: var(--dsw-alias-label-tertiary); font-family: var(--hwb-mono); font-size: 10.5px; padding-top: 1px; }
 .hwb-diag-msg { min-width: 0; }
+.hwb-diag-count { margin-left: 6px; padding: 0 5px; border-radius: 999px; background: var(--dsw-alias-bg-base); color: var(--dsw-alias-label-tertiary); font-family: var(--hwb-mono); font-size: 10px; }
 .hwb-diag-row[data-level="error"] .hwb-diag-msg { color: var(--dsw-alias-state-error-primary); }
 .hwb-diag-detail { display: block; margin-top: 3px; padding: 6px 8px; border-radius: 6px; background: var(--dsw-alias-bg-base); color: var(--dsw-alias-label-secondary); font-family: var(--hwb-mono); font-size: 10.5px; line-height: 1.5; white-space: pre-wrap; word-break: break-word; max-height: 180px; overflow-y: auto; }
 .hwb-diag-empty { padding: 16px 14px; color: var(--dsw-alias-label-tertiary); font-size: 11.5px; }
@@ -620,8 +621,12 @@ header:has([data-slot="conversation.session.header.utilities"]) {
           if (!res.isHtml) store.set({ resolveState: 'invalid' })
           else if (res.exists === true) store.set({ resolveState: 'exists' })
           else if (res.exists === false) store.set({ resolveState: 'missing' })
+          // `exists: null` means the CHECK could not run (no interpreter, no
+          // shell). Staying silent made the field look unresponsive, so promote
+          // the host's reason to the banner instead of dropping it.
+          else if (res.error) store.set({ resolveState: 'idle', error: res.error })
           else store.set({ resolveState: 'idle' })
-        }).catch(() => store.set({ resolveState: 'idle' }))
+        }).catch((e) => store.set({ resolveState: 'idle', error: String(e && e.message ? e.message : e) }))
       }, 300)
     }
 
@@ -674,6 +679,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
       const s = useStore()
       const d = s.diag
       const journal = (d && d.journal) || []
+      const [copied, setCopied] = React.useState(false)
 
       const fact = (key, value) => value == null || value === ''
         ? null
@@ -682,10 +688,53 @@ header:has([data-slot="conversation.session.header.utilities"]) {
           React.createElement('span', { className: 'hwb-diag-val', key: key + '-v' }, String(value)),
         ]
 
+      // A bug report is only useful if it carries the journal. Asking a user to
+      // screenshot a scrolling panel loses exactly the detail lines that matter,
+      // so hand them one paste-ready block instead — plain text, not JSON, so it
+      // survives being dropped into a chat window.
+      const copyReport = () => {
+        const lines = ['# HTML Workbench 诊断报告']
+        if (d) {
+          lines.push('插件版本: ' + (d.version || '未知（可能是动态热加载）'))
+          lines.push('平台: ' + (d.platform || '未知'))
+          lines.push('状态: ' + (d.running ? '运行中' : '未就绪'))
+          lines.push('端口: ' + d.port)
+          lines.push('进程: ' + (d.processStatus || '未由本插件启动')
+            + (d.exitCode == null ? '' : '（exit=' + d.exitCode + '）'))
+          lines.push('Python: ' + (d.pythonCommand || (d.pythonCandidates || []).join(' → ') || '未解析'))
+          lines.push('脚本: ' + (d.script || '未配置'))
+          lines.push('运行目录: ' + (d.runtimeDir || '未知'))
+          if (d.startError) lines.push('失败原因: ' + d.startError)
+        } else {
+          lines.push('（后台未返回诊断信息，通常说明请求根本没有到达 DSH）')
+        }
+        if (s.error) lines.push('界面报错: ' + s.error)
+        lines.push('', '## 日志（最新在前）')
+        if (journal.length) {
+          journal.forEach((entry) => {
+            lines.push('[' + clockTime(entry.at) + '] ' + entry.level + ': ' + entry.message)
+            if (entry.detail) lines.push('    ' + String(entry.detail).replace(/\n/g, '\n    '))
+          })
+        } else {
+          lines.push('（无）')
+        }
+        const text = lines.join('\n')
+        const done = () => { setCopied(true); setTimeout(() => setCopied(false), 1600) }
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).then(done, () => store.set({ error: '复制失败，请手动访问 /html-workbench/diagnostics 获取原始信息。' }))
+        } else {
+          store.set({ error: '当前环境不支持剪贴板，请访问 /html-workbench/diagnostics 获取原始信息。' })
+        }
+      }
+
       return React.createElement('div', { className: 'hwb-diag' },
         React.createElement('div', { className: 'hwb-diag-head' },
           React.createElement('span', { className: 'hwb-diag-title' }, '服务诊断'),
           React.createElement('span', { className: 'hwb-spacer' }),
+          React.createElement('button', {
+            type: 'button', className: 'hwb-btn hwb-btn-quiet hwb-btn-sm',
+            onClick: copyReport, title: '复制完整诊断信息，便于反馈问题',
+          }, copied ? '已复制' : '复制报告'),
           React.createElement('button', {
             type: 'button', className: 'hwb-btn hwb-btn-quiet hwb-btn-sm',
             disabled: s.restarting, onClick: restartService,
@@ -700,8 +749,11 @@ header:has([data-slot="conversation.session.header.utilities"]) {
             fact('状态', d.running ? '运行中' : (d.processStatus === 'running' ? '启动中' : '未就绪')),
             fact('端口', d.port),
             fact('进程', d.processStatus ? d.processStatus + (d.exitCode == null ? '' : '（exit=' + d.exitCode + '）') : '未由本插件启动'),
+            fact('Python', d.pythonCommand || ((d.pythonCandidates || []).join(' → ') || null)),
+            fact('运行目录', d.runtimeDir),
             fact('失败原因', d.startError),
             fact('脚本', d.script),
+            fact('版本', d.version ? d.version + (d.platform ? ' · ' + d.platform : '') : d.platform),
             d.hasShell === false ? fact('shell', '不可用') : null,
           )
           : null,
@@ -713,6 +765,11 @@ header:has([data-slot="conversation.session.header.utilities"]) {
               React.createElement('span', { className: 'hwb-diag-time' }, clockTime(entry.at)),
               React.createElement('span', { className: 'hwb-diag-msg' },
                 entry.message,
+                // Folded duplicates would otherwise read as a single occurrence,
+                // hiding that the user retried and hit the same wall every time.
+                entry.repeated > 1
+                  ? React.createElement('span', { className: 'hwb-diag-count' }, '×' + entry.repeated)
+                  : null,
                 entry.detail ? React.createElement('span', { className: 'hwb-diag-detail' }, entry.detail) : null,
               ),
             ))
@@ -720,7 +777,7 @@ header:has([data-slot="conversation.session.header.utilities"]) {
         ),
         React.createElement('div', { className: 'hwb-diag-hint' },
           '服务自身日志：',
-          React.createElement('code', null, (d && d.logDir) || '/tmp/html-workbench-dsh/logs/'),
+          React.createElement('code', null, (d && d.logDir) || '<工作区>/.html-workbench/logs/'),
           '；也可直接访问 ',
           React.createElement('code', null, '/html-workbench/diagnostics'),
           ' 查看原始 JSON。',

package/src/host.js

@@ -28,29 +28,65 @@ return {
     const PORT = opts.port || 4317
     const SCRIPT = opts.script || null
     const EDITOR_ROOT = opts.editorRoot || null
-    // Static packages inject Node's platform-aware `tmpdir()` from 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. This folder contains only disposable cache/log data.
+    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
-    const RUNTIME_DIR = opts.runtimeDir || (tempRoot ? tempRoot.replace(/[\\/]$/, '') + '/html-workbench-dsh' : '/tmp/html-workbench-dsh')
-
-    // DSH runs plugin subprocesses under a workspace-write sandbox. `~/.cache`
-    // is deliberately outside that allow-list, so the service used to die before
-    // binding the port while trying to open its rotating log. Keep ALL runtime
-    // writes (service logs + downloaded GrapesJS vendor files) in /tmp instead.
-    // This is a cache by design: it is safe to delete and the service recreates
-    // it on the next start.
+    // 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')
@@ -63,17 +99,59 @@ return {
     // 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) => {
-      journal.push({
-        at: Date.now(),
-        level: level,
-        message: String(message || ''),
-        detail: detail ? String(detail).slice(0, 4000) : null,
-      })
-      if (journal.length > JOURNAL_LIMIT) journal = journal.slice(-JOURNAL_LIMIT)
-      if (level === 'error') console.error('[html-workbench] ' + 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);
@@ -86,6 +164,25 @@ return {
       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 = []
@@ -97,10 +194,76 @@ return {
       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 command = 'python3 "' + SCRIPT + '" ' + args
+      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)
@@ -118,9 +281,11 @@ return {
     // 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 + '" health --port ' + PORT,
+          command: python + ' ' + quoteArg(SCRIPT) + ' health --port ' + PORT,
           timeoutMs: 8000,
           stdoutMaxBytes: 64 * 1024,
         })
@@ -137,9 +302,23 @@ return {
       }
     }
 
+    // `/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 probe = await probeHealth()
-      return probe && probe.ok ? probe.payload : null
+      if (!probe || !probe.ok) return null
+      adoptResolvedPaths(probe.payload)
+      return probe.payload
     }
 
     // `workbench.py` reports failures as one structured JSON line on stderr. Turn
@@ -201,11 +380,13 @@ 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
       let proc = null
-      const command = 'python3 "' + SCRIPT + '" serve --port ' + PORT
-        + ' --log-dir "' + LOG_DIR + '"'
-        + ' --vendor-cache "' + VENDOR_CACHE + '"'
-        + (EDITOR_ROOT ? ' --editor-root "' + EDITOR_ROOT + '"' : '')
+      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 {
         note('info', '启动本地服务：端口 ' + PORT, command)
         proc = shell.start(shell.resolve({ command: command, stdoutMaxBytes: 64 * 1024 }))
@@ -220,6 +401,7 @@ return {
             serviceRunning = true
             startError = null
             healthConfirmedAt = Date.now()
+            adoptResolvedPaths(probe.payload)
             note('info', '本地服务就绪：版本 ' + (probe.payload.version || '未知') + '，端口 ' + PORT)
             return probe.payload
           }
@@ -302,12 +484,20 @@ return {
         ok: true,
         running: serviceRunning,
         owned: !!ownedProcess,
+        version: VERSION,
+        platform: PLATFORM,
         port: PORT,
         script: SCRIPT,
         editorRoot: EDITOR_ROOT,
         runtimeDir: RUNTIME_DIR,
-        logDir: LOG_DIR,
-        vendorCache: VENDOR_CACHE,
+        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,
@@ -416,14 +606,24 @@ return {
       if (!trimmed) return { ok: true, empty: true, isHtml: false, exists: false }
       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 }
-      const arg = JSON.stringify(normalized)
-      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 })
+      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), normalized: normalized }
       } catch (e) {
-        return { ok: true, isHtml: true, exists: null, normalized: normalized }
+        return { ok: true, isHtml: true, exists: null, normalized: normalized, error: (e && e.message) || String(e) }
       }
     }
 
@@ -433,13 +633,45 @@ return {
       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', () => listPayload())
-      harness.handle('status', async () => { const h = await health(); const out = diagnostics(); out.ok = !!h; out.running = !!h; out.info = h || null; return out })
+      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', () => diagnostics())
+      harness.handle('diagnostics', () => safeDiagnostics())
       harness.handle('restart', async () => restartService())
     }
 
@@ -462,58 +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, listPayload()),
+        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()
-          const out = diagnostics()
-          out.ok = !!h
-          out.running = !!h
-          out.info = h || null
-          sendJson(res, 200, out)
-        },
+        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')
-      // Readable straight from a browser tab — the fastest path from "red dot"
-      // to "here is the traceback" without any UI in the way.
-      ctx.effect(() => webServer.register({
-        kind: 'exact',
-        path: '/html-workbench/diagnostics',
-        handler: (req, res) => sendJson(res, 200, diagnostics()),
-      }), 'html-workbench: diagnostics route')
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/html-workbench/restart',
-        handler: async (req, res) => {
+        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)
+    })
   },
 }

package/src/index.js

@@ -8,17 +8,76 @@
  * resolved relative to THIS module (`import.meta.url`) — never hard-coded to a
  * specific machine — and handed to the shared body as `config.script`.
  */
-import { readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, resolve, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const scriptPath = resolve(here, '..', 'scripts', 'workbench.py')
-// Runtime state must be writable from DSH's workspace-write sandbox. `tmpdir()`
-// is platform-aware: /tmp on macOS/Linux, %TEMP% on Windows. The content is only
-// logs and a re-downloadable GrapesJS cache, so it is deliberately ephemeral.
-const runtimeDir = join(tmpdir(), 'html-workbench-dsh')
+// The panel shows this next to the diagnostics so a pasted report says WHICH
+// build produced it — without it, every bug report needs a follow-up question.
+const version = JSON.parse(readFileSync(resolve(here, '..', 'package.json'), 'utf8')).version
+
+// Must match RUNTIME_DIR_NAME in scripts/workbench.py, so the host's first guess
+// and the service's own in-process fallback land in the SAME folder instead of
+// scattering two differently named directories through the user's workspace.
+const RUNTIME_DIR_NAME = '.html-workbench'
+
+/**
+ * Whether this process can really create files in `dir` (mkdir + write + delete).
+ *
+ * A writable-looking DACL proves nothing: DSH runs the Python service as a
+ * sandboxed child whose restricted token may write only the session workspace and
+ * a private temp directory it hands the child through TEMP/TMP — never the
+ * ambient %TEMP% root the parent sees. Probing by an actual create is the only
+ * test that reflects what a child can do, and the probe must fail fast (see
+ * `make_temp_file` in workbench.py for why `tempfile.mkstemp` is unusable here).
+ *
+ * A successful probe leaves the directory behind, so it is marked ignored right
+ * away: the runtime root normally sits in the user's own repository, and probing
+ * must not be what dirties their `git status` (see `self_ignore` in workbench.py,
+ * which does the same for the directory the service settles on).
+ */
+const probeWritableDir = (dir) => {
+  try {
+    mkdirSync(dir, { recursive: true })
+    const probe = join(dir, '.wb-write-probe-' + process.pid)
+    writeFileSync(probe, '')
+    rmSync(probe, { force: true })
+    if (!existsSync(join(dir, '.gitignore'))) {
+      writeFileSync(join(dir, '.gitignore'), '# Created by html-workbench: disposable logs and cache.\n*\n')
+    }
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * Choose the runtime directory to ASK the service for.
+ *
+ * The workspace comes first: it is the one tree the sandbox reliably grants and it
+ * keeps the re-downloadable GrapesJS cache across restarts. The historical temp
+ * location stays as a fallback for deployments with no writable cwd.
+ *
+ * This is a request, not a guarantee — the probe runs with the parent's rights,
+ * which are wider than the child's. The service re-probes in-process, falls back
+ * on its own, and reports the directories it really used, so a wrong guess here
+ * costs a different folder, never a failed start.
+ */
+const resolveRuntimeDir = () => {
+  const candidates = [
+    process.cwd() ? join(process.cwd(), RUNTIME_DIR_NAME) : null,
+    join(tmpdir(), RUNTIME_DIR_NAME),
+  ]
+  for (const candidate of candidates) {
+    if (candidate && probeWritableDir(candidate)) return candidate
+  }
+  return candidates[0] || join(tmpdir(), RUNTIME_DIR_NAME)
+}
+
+const runtimeDir = resolveRuntimeDir()
 
 // The body is a `return { ... }` statement; wrap it in a function and call it.
 // eslint-disable-next-line no-new-func
@@ -32,5 +91,6 @@ export const inject = plugin.inject ?? []
 export const apply = (ctx, config) => plugin.apply(ctx, {
   script: scriptPath,
   runtimeDir,
+  version,
   ...(config || {}),
 })