跳转到内容
WebMux

连接、启动与会话总览

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

A. 连接、认证与访问边界

Section titled “A. 连接、认证与访问边界”
  • US-A01 连接服务：作为使用者，我希望在浏览器中连接自己的 WebMux，以便在不安装终端客户端的情况下操作服务器。 验收要点：
    • 登录页、工作区、设置页与浏览器标签页使用统一的 WebMux 标志，明暗主题下均可辨认；
    • 打开页面后检查服务可用性；
    • 显示连接中、连接失败或可用状态；
    • 未设置 token 的服务可直接进入；
    • 设置页按需加载，显示加载状态，下载失败时提示刷新重试。
  • US-A02 共享 token 登录：作为使用者，我希望输入并在本机记住共享 token，以便以后方便地访问自己的会话。 验收要点：
    • 登录页在共享 Token 右侧提供问号提示，默认收起说明；
    • 鼠标悬停、键盘激活或手机点击可查看，指针可移入说明，Escape 或点击外部可关闭；
    • 说明涵盖共享密码用途、初始化生成与保存、配置路径及启动参数覆盖；
    • 配置路径独立成行、窄屏可换行且无横向溢出；
    • 启用认证后，正确 token 才能访问 HTTP API 与 WebSocket；
    • 当前浏览器保存 token；
    • 错误或变更后的 token 触发重新认证提示；
    • 本机套接字采用同用户身份校验，见 US-M08。
  • US-A03 可信网络访问：作为部署者，我希望控制监听地址和允许的浏览器来源，以便只从预期的本机或可信 VPN 入口操作终端。 验收要点：
    • 默认监听所有接口（0.0.0.0:7681），可改为 loopback；
    • 未显式指定配置且默认文件缺失时，首次启动生成并保存 256 位随机 token，非隧道启动不打印该 token，可经本机状态显式查询；
    • 已有配置的 token 为空且监听地址不是 loopback 时，每次启动生成临时随机 token 并打印带 #token= 的本地链接；
    • 只有 loopback 且未启用隧道时允许无 token；
    • 隧道启动仍输出含 token 的链接，持久 token 不因重启失效；
    • 校验 Host 与 Origin，可配置额外完整 Origin；
    • 认证和来源检查同时覆盖终端与文件、仓库、代码接口。
  • US-A04 查看服务与能力：作为部署者，我希望知道服务是否在线、会话数量及 Git/仓库能力是否可用，以便定位连接或环境问题。 验收要点：
    • 健康检查返回可用状态和会话数；
    • 配置接口提供默认目录、主机名和工作区能力，不返回 token；
    • 首页展示连接与能力异常。
  • US-A05 脚本访问：作为进阶使用者，我希望通过 REST 和 WebSocket 操作会话，以便接入自己的脚本或客户端。 验收要点：
    • 提供会话、配置、目录、上传、仓库与代码（含文件操作）接口；
    • 列表和终端分别提供实时流；
    • 遵循相同认证、错误和生命周期边界，详见 协议。
  • US-A06 带凭据链接登录：作为使用者，我希望打开带 token 片段的访问链接就能登录，以便从终端或托盘把入口带到手机。 验收要点：
    • 前端读取并保存 #token= 后立即移除地址栏和当前历史记录中的片段；
    • 片段不发送到服务器；
    • WebSocket 认证通过子协议携带 token，不放入请求 URL 或 Cookie；
    • 链接仍是敏感入口。

依据：

B. 创建会话与选择启动位置

Section titled “B. 创建会话与选择启动位置”
  • US-B01 启动 Shell 或 agent：作为使用者，我希望通过自定义启动配置或显式命令运行 Shell、Open Code、Claude Code、Codex、omp 等程序，以便快速开始终端工作或遥控 agent。 验收要点：
    • 启动命令通过“预先输入 / 手动填写”Tab 区分来源，新安装预置常见 agent 的启动配置，没有不可修改的内置预设；
    • Claude Code、Codex CLI、Gemini CLI、Open Code 与 omp 的预置配置默认自动批准工具调用：
      • Claude Code --dangerously-skip-permissions；
      • Codex CLI --dangerously-bypass-approvals-and-sandbox；
      • Gemini CLI --yolo；
      • Open Code --auto；
      • omp --auto-approve；
    • Cursor、Copilot、Qwen、Kimi、CodeBuddy 使用各自默认授权行为；
    • 九款 CLI 的启动命令见 接入说明；
    • Claude Code、Codex CLI、Open Code 与 omp 预置配置默认为混合模式（US-Q01）；
    • 预先输入以可键盘操作的下拉框选择，选中框和每个选项同时显示图标、名称与命令，长命令保留完整提示；
    • 保存的配置按 ID 启动，临时命令按完整 argv 启动，均创建真实 PTY；
    • Open Code 可通过“加载 shell 启动文件”保存为 Bash（~/.bashrc）或 Zsh（~/.zshrc）包装，新安装按服务端 $SHELL 预选，其他 shell 回退为不包装或手动选择，不自动安装程序；
    • 勾选了混合模式的配置可选择从终端或聊天开始（US-Q02）；
    • 首页与工作树统一使用“新建会话”，分屏菜单复用同一命令选择表单；
    • 创建成功后按入口进入终端或加入当前布局。
  • US-B02 自定义命令与参数：作为进阶使用者，我希望填写完整命令及参数，或选用已保存的配置，以便运行自己的 CLI 工作流。 验收要点：
    • 命令来源 Tab 切换时保留手动输入和已选配置，但只提交当前方式；
    • 空手动命令不能误用保存配置；
    • 正确保留引号、空参数与参数边界，不进行 shell 展开；
    • 未闭合引号或空可执行程序阻止提交；
    • configId 与非空 cmd、env 互斥；
    • 临时命令不落盘，保存配置不可用或仍在加载时可切换手动填写。
  • US-B03 选择直接目录：作为使用者，我希望直接指定任意可访问目录并复用最近使用的位置，以便启动普通项目而不必先登记 Git 仓库。 验收要点：
    • “启动位置”通过“直接目录 / 已有工作树 / 新工作树”Tab 组织，无仓库时禁用两个工作树 Tab；
    • 切换位置保留已填写目录；
    • 默认使用最近目录或服务默认目录；
    • 保留最近 10 个启动目录、上次成功使用的启动配置与临时命令；
    • 已删除或不可用配置回退到手动填写，不隐式启动另一配置。 单仓库视图的全局新建优先预选该仓库的可用主工作区；
    • 没有可用工作区时保留仓库并要求选择，不回退到其他项目。分屏表单以源会话的完整启动目录覆盖最近目录。
  • US-B04 浏览目录：作为使用者，我希望逐层浏览和补全服务器目录，以便在手机上也能准确选中启动位置。 验收要点：
    • 支持路径筛选、主目录、上一级、显示隐藏目录；
    • 支持方向键、Enter/Tab 进入和 Alt+↑ 返回；
    • 显示读取错误并能选择当前目录。
  • US-B05 创建缺失目录：作为使用者，我希望在目录不存在时确认创建再启动，以便直接为新任务准备工作位置。 验收要点：
    • 直接目录启动失败且目录不存在时才提示创建；
    • 确认后创建目录并重试；
    • 不因此登记仓库。
  • US-B06 在已有或新工作树启动：作为使用者，我希望从已有 worktree 启动，或先创建 worktree 再启动 agent，以便在指定的代码副本中工作。 验收要点：
    • 通过启动位置 Tab 进入已有或新工作树面板；
    • 仓库和工作树使用与启动命令相同样式的下拉框，显示名称与路径；
    • 禁用不可用仓库、不可用或 bare 工作树；
    • 切换仓库清空旧工作树选择，切换位置 Tab 保留已填数据；
    • 新工作树成功后可启动会话或仅保留工作树；
    • agent 启动失败时保留新工作树与分支并转到已有工作树面板，重试不重复创建。 仓库菜单的“新建工作树”默认只创建工作树，勾选“创建后启动会话”才显示命令并启动；
    • 启动配置不可用不阻止单独创建工作树。
  • US-B07 命名会话：作为使用者，我希望给新会话填写名称，以便在多个相似终端中识别任务。 验收要点：
    • 创建名称优先于程序标题（终端 OSC 0/2、聊天端 ACP session_info_update）；
    • 未命名时使用程序标题，再回退到目录名；
    • 首页、终端、聊天页头与浏览器标签使用会话标题。
  • US-B08 管理启动配置：作为使用者，我希望把常用的命令、参数和环境变量保存为服务端启动配置，以便在任何设备上一键选用而不必重复输入。 验收要点：
    • 设置页可新建、编辑、删除自定义启动配置，并选择自动匹配、通用终端或 LobeHub 品牌图标；
    • 图标随配置持久保存并在设置列表、新建会话选择器中显示，缺少图标的旧配置按可识别的直接命令或标准 Bash/Zsh 包装自动匹配，不改写原配置；
    • “加载 shell 启动文件”复选框将普通命令安全包裹为所选 Bash 或 Zsh 的交互式 argv，保留空参数、空格和字面量 shell 字符；
    • 重新编辑还原普通命令并保持勾选与所选 shell，保存不重复包裹，取消勾选恢复直接执行；
    • 新建时按服务端只读 defaultShell 预选，空值回退 Bash；
    • 包装参数计入 argv 上限；
    • 可为每条配置选择跟随全局默认或单独设置输出预览行数与跳过末尾行数；
    • 新安装首次启动时自动写入 Shell、九款 CLI agent 与 omp 共 11 条带图标的启动配置（完整列表见 接入说明），其中 omp 附带 PI_FORCE_IMAGE_PROTOCOL=kitty 以启用 US-D12 图片显示；
      • Shell 为通用终端，agent 使用本地打包的 LobeHub 图标，omp 使用 Pi；
      • agent 预设按服务端 $SHELL 经“加载 shell 启动文件”包裹（Bash 或 Zsh，未设置时 Bash，其他 shell 直接执行）；
      • 各命令的授权参数见接入说明，Claude Code、Codex CLI、Open Code 与 omp 为混合模式，可编辑或删除；
    • 文件已存在时（包括用户编辑或删空后）不再补写或覆盖；
    • 配置跨重启与设备共享，环境变量值默认遮挡；
    • 按配置 ID 启动，修改或删除配置不影响运行中会话的命令与环境，会话信息保留配置 ID 供首页解析预览；
    • 存储不可用时显示原因，临时命令仍可用。编辑器可勾选混合模式，可用性由服务端判定并显示原因，列表显示“混合”标记（US-Q01）。

依据：

来源补充：统一创建回归。

C. 会话总览、搜索与提醒

Section titled “C. 会话总览、搜索与提醒”
  • US-C01 按项目总览：作为同时处理多个任务的使用者，我希望按仓库、工作树和会话查看工作，以便快速理解每个任务在哪里运行。 验收要点：
    • 左侧导航切换单仓库、全部仓库或直接会话，每项显示对应范围的会话及等待数，长列表独立滚动；
    • 桌面主屏幕应用中的导航避开实际高度变化的吸顶页头，列表高度随之调整；
    • 窄屏选中后收起并恢复按钮焦点；
    • 首次多仓库进入优先选有会话者，明确选择在当前浏览器记忆，已移除仓库回退全部，读取失败不覆盖偏好；
    • 从终端返回首页先渲染上次成功快照并后台刷新 Git，慢读取不显示启动超时错误；
    • 仓库可折叠；
    • 直接会话按启动目录分组，失效工作树中的会话仍可访问；
    • 仓库路径与工作树比例收在仓库菜单详情，工作树路径及总数、运行/等待/退出计数收在详情按钮中；
    • 首页不展示底部品牌、仓库持久化及可信网络/重启说明栏；
    • 会话与仓库管理表单按需加载，加载中可取消，下载失败可关闭提示，取消后不会迟到弹出。
  • US-C02 实时查看会话摘要：作为使用者，我希望在首页看到标题、状态、最近活跃时间、连接设备数和输出预览，以便少打开几个终端就能判断进度。 验收要点：
    • 默认显示输出预览，可切换为只保留会话摘要的紧凑列表，显式选择的显示方式在当前浏览器记忆；
    • 列表先加载快照再处理实时事件；
    • 创建、更新、移除自动反映；
    • 状态标签紧跟标题，下一行依次为所在端（混合会话）、连接设备或“后台会话”与最近活跃时间，状态变化不移动其他内容；
    • 没有客户端的会话显示为后台会话；
    • 高频输出保留未变化会话的对象与创建顺序，不反复排序全表；
    • 最近活跃时间每 30 秒及回到前台时校准；
    • 会话卡片按创建时使用的启动配置显示其预览设置，配置缺失或首页加载时存储不可用则回退全局设置，打开新建会话重新读取期间或失败时保留已加载的预览。混合会话卡片标出所在端，聊天端以最新 agent 消息代替终端预览；
    • 已关闭或已中断的混合会话不在运行中分组，只出现在“可恢复”分组（US-Q09、US-Q12）。
  • US-C03 稳定浏览列表：作为使用者，我希望后台输出不会移动正在点击的会话卡片，以便可靠地选择目标。 验收要点：
    • 组内会话按创建时间倒序排列；
    • 输出和状态变化不触发活跃度重排；
    • 预览模式始终预留设定高度；
    • 切换仓库与筛选复用会话行并关闭隐藏项菜单；
    • 会话菜单首次打开后，鼠标、方向键、Escape 关闭与焦点恢复均可继续使用。
  • US-C04 搜索与状态筛选：作为使用者，我希望按名称、目录、仓库或分支搜索，并结合运行、等待、退出筛选，以便从大量会话中找到目标。 验收要点：
    • 搜索与状态条件在当前仓库范围内叠加，状态计数和辅助技术播报的仓库/会话总数随范围及实时数据更新；
    • 目录匹配包括启动目录和 Shell 报告的目录与主机；
    • 运行筛选包含 running 与 idle；
    • 搜索可展开匹配仓库；
    • 支持清除筛选、无匹配提示和 / 聚焦搜索，输入框与弹窗中不抢快捷键；
    • 筛掉的卡片不参与键盘导航或辅助技术浏览，并关闭该卡片已打开的菜单；
    • 清除筛选恢复卡片顺序，删除会话后移除对应卡片。
  • US-C05 判断运行状态：作为使用者，我希望区分运行中、可能在等我、空闲和已退出，以便决定先查看哪个任务。 验收要点：
    • 程序通过 OSC 7501 报告状态时以报告为准（工作中、阻塞、完成、空闲），工作中但长时间无输出视为空闲；
    • 否则依据关注信号、近期输出、提示符模式和终端读取给出启发式标签；
    • 曾发出 OSC 7501 或 Warp 结构化信号的程序不再触发“可能在等你”的启发式；
    • 计时休眠不直接当作等待输入；
    • 退出后显示退出码；
    • 状态只展示，不自动回答或执行操作。
  • US-C06 接收 agent 介入提醒：作为遥控 agent 的使用者，我希望明确看到需要回答、等待授权、本轮完成或出错停止，以便及时处理任务。 验收要点：
    • 支持 OSC 7501 程序状态、Warp 结构化 agent 事件、终端通知和 BEL 响铃，按此顺序分层：存在 OSC 7501 状态时只由其变化决定提醒，较低层不覆盖或清除较高层；
    • 服务端在无浏览器时也应答 OSC 7501;? 探测，使 Claude Code 等需探测的 agent 报告状态，回放不重答，webmux attach 不把探测转给本地终端；
    • 具体提醒优先于启发式状态，持续输出和重连不清除；
    • 用户输入、agent 报告重新开始或空闲、提示符作废或退出时清除，重复报告不在处理后再次提醒；
    • 只解析状态与种类，不保存正文。
  • US-C07 调整输出预览：作为使用者，我希望控制预览行数并跳过 agent 的底部状态栏，以便首页突出有用输出。 验收要点：
    • 输出预览模式显示 1–50 行、跳过末尾 0–50 行；
    • 默认显示 10 行、跳过 1 行；
    • 提供示例与恢复默认；
    • 有效设置保存在服务端并跨设备同步，无效值不覆盖设置；
    • 启动配置可单独覆盖行数与跳过值并选择跟随全局默认，未配置或配置不可用时使用全局值。
  • US-C08 刷新外部 Git 变化：作为使用者，我希望终端外发生的工作树变化也能出现在首页，以便总览反映磁盘现状。 验收要点：
    • 打开首页、回到前台、重连、手动刷新和相关操作后重新读取 Git；
    • 读取时间收在仓库菜单详情，错误始终可见；
    • 较旧的请求结果不能覆盖新结果。
  • US-C09 切换明暗主题：作为使用者，我希望页面和终端适应自己的明暗偏好，以便舒适阅读。 验收要点：
    • 未选择时跟随系统主题；
    • 可手动切换并在服务端保存；
    • 已连接设备同步主题选择；
    • 终端颜色随主题更新。
  • US-C10 区分启动与当前目录：作为在终端里 cd 的使用者，我希望首页同时看到会话的启动目录和 Shell 报告的当前目录，以便知道任务实际在哪里而不误判归属。 验收要点：
    • 接受 OSC 7 file://主机/绝对路径 报告，拒绝凭据、端口、查询、控制字符和超长值；
    • 会话仍按启动目录及其工作树分组，报告目录只单独展示；
    • 非本机主机标注「远端」；
    • 菜单复制报告目录，无报告时复制启动目录；
    • 进程退出后清除；
    • 不改写 shell rc、不采集命令正文。
  • US-C11 新标签页打开终端（已退役）：作为在多个会话间切换的使用者，我希望从会话列表打开终端时保留列表页，以便继续观察其他任务而不用回退或重新加载。 验收要点：
    • 已退役（2026-10-28）：会话卡片改为在当前标签页打开终端，由 US-C14 取代；
    • 需要新标签页时可用浏览器的中键或 Ctrl/⌘ 点击。
  • US-C12 后台接收推送提醒：作为离开页面或锁屏的使用者，我希望收到需要回答、等待授权、本轮完成、出错或终端通知的推送，以便及时回到对应会话。 验收要点：
    • 设置页按设备开启或关闭推送，开启时只请求一次浏览器通知授权，显示服务端订阅数，并可从任一设备向全部设备发送测试通知；
    • 仅安全上下文与支持的来源（已授权的 HTTPS 入口，含 Tailscale Serve/Funnel，或本机回环）提供开关，否则给出 HTTPS 入口、Quick Tunnel、iOS 主屏幕、浏览器能力、权限或服务端配置等可执行提示；
    • 推送标题为会话标题，include_title = false 或标题为空时为 WebMux，正文以与会话列表一致的短标签开头并给出下一步；
    • 测试通知说明推送已生效；
    • 点击通知聚焦或打开 /s/<ID>，不跟随负载中的其他地址；
    • 负载不含 cwd、命令、预览、OSC 正文或终端输出；
    • 送达为尽力而为，列表状态仍是唯一准确来源。
  • US-C13 浏览器标签页运行指示：作为切到其他标签页或应用的使用者，我希望标签页图标与标题显示当前是否有任务正在执行，以便一眼看出任务是否仍在运行。 验收要点：
    • 仅当前终端会话或首页任一会话 status === "running" 时，标题增加 ▶ 前缀并循环播放本地生成的 favicon 动画；
    • waiting、idle、exited 不播放“执行中”动画并恢复静态图标与基础标题；
    • 动画约 1–2 fps，不产生逐帧网络请求，不读取或输出终端正文；
    • prefers-reduced-motion: reduce 时图标保持静态运行帧、标题仍保留标记；
    • 刷新、断线重连、切换标签页或状态更新后指示与最新 status 一致；
    • 状态沿用启发式判定，长时间无输出的命令可能在 idle_after_seconds 后停止动画。
  • US-C14 当前标签页打开终端：作为在会话列表与终端之间来回切换的使用者，我希望点击会话卡片直接进入终端，以便不在浏览器中堆积标签页。 验收要点：
    • 点击会话卡片在当前标签页进入 /s/<ID>，不打开新标签页、不整页重新加载；
    • 链接不带 target，悬停不再提示“在新标签页打开”，标题旁的箭头改为向右的 chevron；
    • 中键或 Ctrl/⌘/Shift 点击保留浏览器默认的新标签页或新窗口行为；
    • 终端页“返回会话列表”回到首页，列表继续实时更新；
    • 主屏幕应用同样在应用内导航。

依据：