跳转到内容
WebMux

终端使用

基于 main@306d253 的文档在 GitHub 上查看编辑此页

  • 进入终端时先回放服务端缓冲，再续接实时输出；断线后以指数退避（0.5–8 秒）自动重连，回到前台时立即重新附着。若本页终端仍在且服务端还保留断线后的输出，只补发缺失部分，不清屏；否则清屏全量回放。缓冲已覆盖最早输出时，菜单“复制全部缓冲”会注明。

  • 同一会话可在多个设备（浏览器标签页）上同时打开，任一端的输入其他端可见。只有控制端决定 PTY 尺寸：

    • 首个打开的设备成为控制端，之后的设备先观察，顶部显示“观察中 · 某设备控制输入与尺寸”。
    • 观察端按控制端的行列显示，超出屏幕时可拖动平移。
    • 键盘开合、窗口变化或重连都不会改变 PTY 尺寸。
    • 在观察端输入、发送草稿、点 ⌨ 或“接管控制”即取得控制权；控制端离开后控制权空缺，直到下一次输入。
    • 终端设备查询只由控制端（无控制端时为最早连接）回答。

  • 顶栏：

    • 左侧是返回、标题和状态点。
    • 右侧从左到右依次为混合会话的“聊天 | 终端”切换、上传与“滚动到最新位置”、快捷指令入口、草稿、代码工作区、全屏和菜单。
    • 菜单中可复制全部缓冲、清屏、重新同步、调整字体、锁定尺寸和关闭会话。
    • 连接正常时顶栏不显示文字（状态点的提示包含“已连接”），重连中、已退出或会话不存在时在状态点旁显示。

  • 窗口窄于 640px（手机竖屏）时，顶栏只保留返回、标题、状态、快捷指令入口、草稿、终端 / 代码切换和菜单；全屏、上传文件和滚动到最新位置移到菜单顶部。向上翻看历史时，终端右下角出现“回到最新”按钮。

  • 已退出的会话保留退出码和最后输出，直到手动移除。

  • 关闭会话先发送 SIGHUP，5 秒后仍未退出则发送 SIGKILL，并清理整个进程树。

查找终端输出

Section titled “查找终端输出”
  • 在终端菜单选择“查找终端输出”，或按 Ctrl+Shift+F（macOS ⌘F）；普通 Ctrl+F 仍发送给终端。手机在代码视图打开查找时会切回终端。
  • 输入文字即时查找，支持区分大小写、全词和正则；Enter / Shift+Enter 导航，Esc 关闭并清除高亮与选区。查找输入不发送给 PTY，也不改变终端网格；草稿模式同样可用。
  • 查找仅覆盖浏览器 xterm 当前保留的活动缓冲：普通终端最多回看 10000 行，全屏程序只搜索当前屏幕，不代表完整日志。服务端历史已覆盖时另显示截断提示；计数达到上限显示“至少 1000 个匹配”，仍可继续导航。查找完全在浏览器中完成，不使用新的搜索 API，也不扩大 /api/sessions/{id}/buffer 的保留范围。
  • 全量回放、清屏及普通/全屏缓冲切换会清除旧结果；查询词保留，全量回放完成后按 Enter 重新查找。增量续接保留查找位置；退出会话仍可查找最终输出。
  • “复制选中”复制解析后的可读文本；剪贴板不可用时提供手动复制框。原有“复制全部缓冲”与 buffer API 仍返回原始字节，不是可读日志导出。

终端右上角的键盘图标打开“快捷键”，按场景查看 WebMux 的键位及生效范围，包括分屏、复制粘贴、终端查找、代码阅读和布局调整。入口在窄屏可见，列表可滚动；按 Esc 或点击关闭后焦点返回入口。Shell 和 CLI 自身的键位由当前程序决定。

终端分屏

Section titled “终端分屏”

顶栏的“分屏”菜单支持嵌套分屏，最多同时打开 8 个窗格：

  • 新建会话…：复用完整创建表单，可选保存的启动配置或临时命令、填写名称并选择左右或上下分屏；创建成功后加入当前布局，取消不创建会话。
  • 快速新建 Shell：用“左右分屏 · 新建 Shell”或“上下分屏 · 新建 Shell”直接执行 /bin/sh -i，不经过表单。
  • 加入已有会话…：搜索并选择现有 Shell 或 agent，不创建新会话。

完整创建表单默认沿用源会话的完整启动目录；快速 Shell 也使用该目录，关联工作树时保留子目录并校验工作树。创建新工作树后若命令启动失败，工作树会保留，切换仓库再返回仍可选择它重试。

  • 点击窗格或顶部窗格按钮切换操作目标；每个窗格拥有独立的终端、草稿和代码面板。拖动分隔条调整大小，双击恢复等分；聚焦分隔条后可用方向键调整，Home/End 调到边界，Enter 恢复等分。
  • “放大窗格”暂时只显示当前窗格，再次点击恢复原有布局。窄于 768px 时自动只显示当前窗格，通过顶部按钮切换，宽屏恢复原来的分屏比例。
  • 布局、比例和当前窗格按入口会话保存在当前浏览器，刷新或从同一链接进入可恢复；本机存储不可用时仅在当前页面保留，不在设备间同步。会话已失效时显示不存在提示，可关闭对应窗格。
  • “关闭窗格（保留会话）”只解除该窗格的连接，进程继续运行，可从列表或“加入已有会话”再次打开。需要终止进程时，仍使用终端菜单中的“关闭会话”并确认。

在终端输入区先按 Ctrl+B，释放后再按下表中的键（不作用于草稿框、代码面板或弹窗）：

后续按键操作
%左右分屏并新建 Shell
"上下分屏并新建 Shell
方向键 / o按方向 / 循环切换窗格
z放大当前窗格 / 恢复分屏
x关闭当前窗格，保留会话
Ctrl+B向当前终端发送原始 Ctrl+B（可继续操作内层 tmux）
Esc取消前缀

复制与粘贴

Section titled “复制与粘贴”
  • 桌面有选中文字时按 Ctrl+C 复制并清除选择，无选中时照常发送 SIGINT；macOS 使用 ⌘C 复制，Ctrl+C 始终发送 SIGINT。Ctrl+Shift+C 不再作为复制快捷键。粘贴使用 Ctrl+Shift+V。
  • 粘贴遵循程序启用的 bracketed paste 模式，Bash、Claude Code 等程序中多行文本不会被逐行提交。
  • 当前可见终端通过 OSC 52 发出的复制请求会写入浏览器剪贴板；后台或被代码/聊天遮住的终端只保留最新请求，显示待处理提示，主动点击“复制待处理文字”后才复制；切换窗格不会自动复制，重连回放历史不会重复触发。
  • HTTP 环境下 Clipboard API 不可用时，快捷键与复制按钮改用 execCommand 回退；OSC 52 复制请求没有用户手势，仍回退为可手动复制的文本框。

终端图形

Section titled “终端图形”

  • 浏览器终端支持 Kitty 图形协议 的直接传输：PNG、24 位 RGB 与 32 位 RGBA、分块传输、图片与放置 ID、图像编号、源矩形裁剪、按单元格缩放与偏移、C=1 光标策略，以及按 ID、位置、z-index 等删除。

  • 程序发送协议查询（a=q）时，由正在渲染该会话的控制端浏览器应答，程序可据此自行启用图形输出；会话回放不会重复回发历史查询的应答。

  • 图片只在浏览器终端中绘制，不进入会话列表的文本预览。文件/共享内存等本地传输介质、动画、Unicode 占位符与相对父放置尚不支持；相对放置请求返回 ENOTSUP，不悄悄画到错误位置。负 z-index 图片仍绘制在文字上方，而不是文字下方。

  • 普通/备用屏幕的图片互相隔离。清屏与擦除对图片的影响如下：

    • CSI 2J 清屏删除当前屏幕中的放置，但保留可复用的图片数据。
    • CSI 0J/1J 等局部文本擦除不删除图片。
    • CSI 3J 只随历史缓冲截断释放已移除历史行上的图片。
    • 图片跟随输出滚动，查看历史时可重新显示；omp 的 ESC7/CUU/y/h/ESC8 顶部裁剪重绘不会被随后文本擦除误删。
    • 完整重新同步和离开页面会释放旧图像状态。

  • 图片解码、放置数量和画布显存均有上限；达到上限时拒绝新的请求，不先分配超大画布。后续字体、窗口或 DPR 变化使放置超限时移除该放置，终端文本继续工作。

在 omp 中显示图片

Section titled “在 omp 中显示图片”

新安装预置的 omp 启动配置自带 PI_FORCE_IMAGE_PROTOCOL=kitty，保留“加载 shell 启动文件”包装（Bash 或 Zsh，按服务端 $SHELL 选择）；直接选用该配置即可。已有 launch-configs.json（包括用户编辑或删空的配置）不会被覆盖；升级后可在自己的 omp 启动配置中补上该环境变量。

本机 omp 18.12.6 在未设置该变量的默认终端环境中只显示图片文字占位，不会自动发出 Kitty 传输；临时命令也可显式启动：

终端窗口
PI_FORCE_IMAGE_PROTOCOL=kitty omp

该选项使用 omp 官方的协议覆盖，不把 WebMux 伪装成完整 Kitty 终端，也不改变其他启动配置。

  • 不要启用 Kitty Unicode 占位符；该扩展不在当前支持范围内。
  • 验收需要交互式终端：在隔离实例中，真实交互式 omp 的图片读取结果已发出 a=t,f=100 PNG 传输，再以 a=p,C=1 放置；仅运行 omp read 的诊断命令或离线 omp render 不能代替。

开发者可在仓库目录的 WebMux 会话中运行最小复现程序（Node.js 26）：

终端窗口
node web/test/fixtures/kitty-scroll-demo.mjs

按上/下方向键切换完整图片和顶部裁剪，按 r 只重绘文字而不重发图片，按 q 退出。重绘后色带应保留；该程序与浏览器回归共用协议字节，覆盖 PNG 传输、显式删除、保存/恢复光标与裁剪放置。

文件上传

Section titled “文件上传”

点击“上传文件”、把文件拖入终端，或粘贴剪贴板中的文件 / 图片。上传完成后，带 shell 引号的服务器绝对路径会插入终端（不回车）。

  • 文件保存在本会话临时文件夹的 uploads/ 中：$TMPDIR/webmux-artifacts-<uid>-<实例摘要>/<会话ID>/uploads/，权限 0700 / 0600，不写入工作区；同名文件追加 (2) 等序号，不覆盖。
  • 单文件上限 100 MiB，上传期限 5 分钟，可随时取消。
  • 会话删除后其临时文件夹（含上传文件）随之删除；混合会话保留到删除可恢复记录为止。服务启动时清扫无主的文件夹。

会话临时文件夹

Section titled “会话临时文件夹”

每个会话可以有一个只属于它的临时文件夹，用于和 agent 交换文件：上传素材在 uploads/，agent 生成的截图、报告、图表等交付物也放在这里，而不是项目仓库。

  • 在代码栏导航顶部切换到“临时文件夹”即可浏览、搜索和预览这些文件；目录可写时同样支持上传、下载、新建、重命名、复制、移动与删除（见代码工作区）。首次切换时创建文件夹。
  • 快捷指令（⚡）菜单顶部的“插入临时文件夹提示词”会把说明文件夹用法的提示词（含真实路径）插入终端或草稿，不回车。
  • 提示词模板在“设置 → 快捷指令”中编辑，用 {dir} 代表文件夹路径；“恢复默认”回到内置模板。

在混合会话的聊天视图，输入框左侧的回形针、拖放到聊天视图或粘贴文件 / 图片同样上传，完成后作为下一条消息的附件（可移除的 chip），不插入路径、不自动发送；上传中可查看文件名、序号与百分比并取消。附件的发送与降级见 混合会话。