Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

[Gen UI] Inline visualize cards always fail on SSH remote executors (desktop-attached-remote): "Gen UI file is outside the host output directory"

未关闭
  • 哪里不对？
#76 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
43/100
Issue 类型
缺陷
描述清晰度
描述清楚
活跃度
活跃
技术栈
javascript, node.js
领域
backend, desktop

调研方向

Start with packages/services/src/gen-ui/adapters/files.ts and the readGenUiDocument path described in the report, then read docs/architecture/r2-server-cli-and-daemon.md to confirm executor ownership. Trace how desktop-attached remote reads reach the executor and compare that with the local validation path. Done when the remote executor validates the file against its output root and returns its HTML for the client card to render.

由索引模型根据 Issue 内容生成。

描述

Note: filed here because github.com/zai-org/ZCode has issues disabled; this repo already hosts main-repo bug reports (see #64, #60). Happy to repost if the team prefers another channel.

Environment

  • ZCode Desktop client 3.15.1 (Windows 11), latest
  • Remote executor over SSH: Ubuntu 24.04 (root), zcode-server 3.15.1 (matched), service authority mode desktop-attached-remote
  • Executor env: ZCODE_GEN_UI_OUTPUT_ROOT=/root/.zcode/v2/visualizations

Steps to reproduce

  1. Connect Desktop to an SSH remote executor (WSL2 Ubuntu) as a remote workspace
  2. Ask the agent to emit any ::visualize fragment; the executor writes it into the host-injected session dir, e.g. /root/.zcode/v2/visualizations/<sha256(workspace-identity,session-id)>/view.html
  3. Client renders the Gen UI card

Actual behavior

Card fails to load: Gen UI file is outside the host output directory（客户端提示“无法加载交互视图”）。100% reproducible across multiple files; “重试” never helps.

Executor-side checks (all pass)

  • File is inside ZCODE_GEN_UI_OUTPUT_ROOT; directory name = sha256 of [workspace-identity, session-id], exactly as injected by the host
  • Permissions 644, no symlinks on the whole path (verified with namei), valid HTML fragment, well under 5 MB
  • The error string exists in zcode-server.cjs (readGenUiDocument), but at read time the failing validation cannot be the executor's own — the file is under the executor root, so the relative() check would pass there

Root-cause analysis (from the client bundle + repo source)

  • The Desktop client bundle (app.asar 3.15.1) embeds the same reader — readGenUiDocument (minified bL) of packages/services/src/gen-ui/adapters/files.ts: 
    let r = resolve(t),            // t = outputRoot, resolved on the LOCAL client machine
    o = normalize(n.path),     // n.path = remote executor's absolute POSIX path, e.g. /root/.zcode/v2/...
    s = relative(r, o);
if (!s || s === ".." || s.startsWith(`..${sep}`) || isAbsolute(s))
    throw new Error("Gen UI file is outside the host output directory");
    relative() between a Windows local output root and the remote absolute path can never pass, so the client throws before any remote access happens.
  • packages/services/src/gen-ui/adapters/files.ts (current main) states the intended design in a comment: “读取范围只由执行端 Host 的固定输出根目录决定” — the read scope is owned by the executor-side Host. docs/architecture/r2-server-cli-and-daemon.md places the same ownership on the executor.
  • Conclusion: in desktop-attached-remote mode the Gen UI document read/validation is not dispatched to the remote host; the client performs a local-filesystem read with a local output root instead.

Expected behavior

In desktop-attached-remote mode, route the Gen UI document read/validation through the remote transport: the executor validates against its own ZCODE_GEN_UI_OUTPUT_ROOT and returns the HTML content to the client for rendering.

Impact / current workaround

Only inline interactive Gen UI cards are affected; all other remote functionality works fine. Current workaround: executor delivers Playwright PNG screenshots plus standalone HTML files instead of ::visualize cards.

Notes

  • No user-facing configuration found that redirects the client-side validation root (ZCODE_GEN_UI_OUTPUT_ROOT only configures the executor side).
  • Happy to provide full connection logs or a minimal repro if useful.
主要语言
Python
星标
95
派生
57
30 天内没有已合并 PR

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

zai-org/zcode-plugins 的其他 Issue

查看 zai-org/zcode-plugins 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。