混合会话

Q. 混合会话（聊天 ↔ 终端）

• US-Q01 开启混合模式：作为使用者，我希望在启动配置上勾选混合模式，以便之后用这条配置启动的 OpenCode、omp、Codex CLI 或 Claude Code 会话能在聊天视图与终端之间切换。 验收要点：
  • 新安装预置的 OpenCode、omp、Codex CLI 与 Claude Code 配置已勾选混合模式，已有 launch-configs.json 不被改写；
  • 设置页编辑器提供“混合模式（聊天 ↔ 终端）”勾选框，可用性只取服务端判定（打开时用配置的 hybridSupport，改命令后去抖查询 hybrid-support）；
  • 不可用时禁用并显示原因：未识别的 agent、命令写法、会话库或目录参数、非交互参数、codex resume/fork、Claude Code 的 --continue/--resume/--session-id 等打开已有会话的参数，以及 Claude 的 --worktree/--tmux、--no-session-persistence/--environment 与非交互参数；
  • 未识别的 agent 与勾选框说明列出服务端返回的受支持 agent（supportedAgents，来自 agent 注册表）；
  • 勾选不受支持的命令保存返回 400，保存不检查第三方连接器是否已安装；
  • Claude Code 使用稳定档案 ID claudecode，允许 CLAUDE_CONFIG_DIR 环境但不允许命令内会话参数；
  • 列表显示“混合”标记；
  • launch-configs.json 仍为 v2，未勾选时不写入字段，旧文件照常读取。
• US-Q02 选择起始端：作为使用者，我希望新建混合会话时选择从终端或从聊天开始，以便在电脑上直接用 TUI、在手机上直接对话。 验收要点：
  • 选中混合配置时显示“从终端开始 / 从聊天开始”，默认终端并按浏览器记住；
  • 从终端开始在 PTY 中运行配置命令（OpenCode 注入 --standalone，命令中可见）；
  • 从聊天开始启动 ACP 进程并新建 agent 会话，PTY 中没有进程；
  • 普通配置或手动命令带起始端返回 400；
  • 记录存储不可用 503、记录已满 409。
• US-Q03 从终端切到聊天：作为在电脑上用 TUI 的使用者，我希望离开电脑前一键切到聊天视图，以便在手机上继续同一段对话。 验收要点：
  • 头部“聊天 | 终端”控件只在满足六个条件时可切，否则禁用并显示原因：
    • 受支持的 agent；
    • 档案需要的第三方连接器已安装；
    • 是 PTY 根进程（Codex 与 Claude Code 也接受 npm 的 node 启动器及其唯一直接原生 agent 子进程）；
    • 已有 agent 会话 ID：Codex 取自写锁；Claude 取自 <CLAUDE_CONFIG_DIR>/sessions/<pid>.json，采用前核对 PID、UUID、规范化 cwd、进程启动标识与 PID domain，失效时退回 cwd + 启动时间的 session/list 候选，多个候选时让用户选择；首条消息前即使已有注册 UUID，list 不含可加载会话仍不可切换；
    • 会话列表能查到；
    • 未被其他会话占用；
  • TUI 在回合中时先发中断键并等待空闲（Claude Code 为一次 Esc；Codex 启动阶段的“工作中”不算回合，Claude 无启动静默期），10 秒后可选继续等待、强制切换或取消（强制切换的损失说明取自服务端 forceSwitchNote，由各 agent 适配器提供）；
  • 进入目标端前确认 TUI 进程组已退出；
  • 聊天视图回放完整历史，模型等配置与切换前一致（按档案补齐 omp 的 mode 与 Codex 的模式、模型、推理强度，Codex 首次切换按启动参数推导；Claude 首次从 argv 推导 model/effort/mode，冷 load 与 resume 后重应用 model/effort，mode 保留连接器从 transcript 恢复的实际值，回退显示实际配置与通知）；
  • 会话被 webmux 之外的 Codex 客户端或被有效注册记录识别的 Claude 进程占用时回到终端并提示 occupied_external，当前/退出/陈旧 Claude 记录不误报，来源不可读时仅保留内部检测且不保证发现所有外部写者；
  • Claude 注册读取有频率/大小/条目上限，普通会话不扫描，路径、PID、启动标识、记录正文与凭据不进入客户端负载、混合记录或日志；
  • 已附着的终端以 4409 断开。
• US-Q04 从聊天切回终端：作为在手机上对话的使用者，我希望回到电脑后切回原生 TUI，以便继续精细操作。 验收要点：
  • 回合进行中先确认，再取消回合并把挂起的请求答复为取消；
  • 排队中未发送的消息合并后退回发起设备的草稿，其他设备只收到提示，不自动发给 TUI；
  • agent 支持时 session/close 后结束 ACP 进程并等待退出，再以恢复命令在同一会话 ID 下启动新运行代际（Claude 为 --resume <id>）；
  • Claude 的 cancel 只中断当前回合，后台 Bash 或子任务可能存活，切换须终止连接器并等待受管后代退出，不保证任意自行 daemonize 的进程已清理；
  • 切换期间显示“中断、退出、启动、连接终端”进度，直到新运行在本页输出首屏（最多 10 秒）才淡入终端，不显示空白终端；
  • 页面列出恢复时未保留的参数；
  • 任一步失败自动回到原端并显示原因。
• US-Q05 阅读聊天时间线：作为手机上的使用者，我希望以对话形式阅读 agent 的输出，以便比滚动终端更容易理解进度。 验收要点：
  • 用户消息为气泡、agent 消息为正文，思考默认折叠；
  • 工具调用显示一行摘要可展开，连续读取与搜索合并为“已浏览 N 项”，diff 显示增删行数并可在代码面板查看，同一 toolCallId 的更新只保留一行；
  • 回合状态由服务端记录 startedAt / endedAt，进行中每秒显示已用时间，结束后保留总用时，刷新、重连与其他设备不重新计时；
  • 计划、用量（输入框旁的上下文用量环，点击弹出已用、上下文窗口、剩余 token 与费用）、压缩、提示与回合结束（已中断、错误）分别呈现；
  • 不支持的内容显示占位；
  • 断线重连只补发缺失事件；
  • 超出 scrollback_bytes 的旧事件丢弃并在顶部提示“更早的历史未缓存，可切到终端查看”。
• US-Q06 答复权限与表单：作为使用者，我希望在聊天视图直接批准工具调用或回答 agent 的提问，以便不必切回终端。 验收要点：
  • 权限请求以编号选项显示在输入框位置并标注在对应工具调用上；
  • 表单渲染字符串、枚举与布尔字段，其他字段提示需在终端完成且只能拒绝或取消；
  • 多设备同时作答时第一个生效，其余返回 409 answered 并随即看到请求关闭；
  • 切换或停止回合时挂起请求被取消。输入框下方的“权限”选择（“自动批准”默认 / “每次询问”）在宽屏是输入框下方的图标按钮，窄屏收进上传按钮旁的“会话选项”弹层，悬停提示与可访问名保留“权限：当前值”，菜单显示完整名称；
  • 选择经 PUT .../chat/permission-mode 保存在服务端并在所有设备同步：自动批准时 webmux 直接选择第一个“允许一次”、其次“始终允许”的选项，不打开请求、不产生提醒，时间线不显示批准提示；
  • 切到自动批准时挂起的权限请求随即批准；
  • 没有允许选项的请求与表单仍交给用户；
  • Claude 的工具权限请求与拒绝使用同一管线，agent 的 default/auto/bypassPermissions 等模式与这里的 webmux 自动批准设置各自显示，运行条件回退时采用连接器实际配置与通知；
  • 模式写入混合会话记录，切换、休眠唤醒与恢复后保持；
  • 保存期间选择禁用，失败在输入框上方提示。
• US-Q07 调整配置与使用命令：作为使用者，我希望在聊天视图切换模型等配置并使用 agent 的斜杠命令，以便不切回终端也能调整 agent。 验收要点：
  • 输入框下方显示 agent 提供的配置项（选择类为下拉、布尔类为开关），两者都按 category 显示图标，未知类别使用通用图标，完整名称与当前值放在提示、可访问名和菜单中，宽度不足时这一行横向滚动而不换行；
  • 变更经 session/set_config_option 生效并在所有设备同步，取值被记录用于切换与恢复后补齐；
  • Claude 首次从 --model、--effort 与权限 argv 播种，manual 映射为 ACP default、危险跳过权限优先映射 bypassPermissions，不支持的值列入不生效参数；
  • 冷 session/load 与 session/resume 后重应用记录的 model/effort，mode 以 transcript 恢复值为准，不回写过期 argv，回退显示实际值与通知；
  • 输入 / 打开随输入过滤的命令菜单。
• US-Q08 排队与插话：作为使用者，我希望 agent 忙时继续发送消息并按顺序处理，以便不必等待也不会打断当前回合。 验收要点：
  • 服务端队列多设备共享：空闲且未暂停时立即发送，否则排队，回合正常结束后逐条发送；
  • 队列可编辑、上移、删除、二次确认后立即发送；
  • 回合被停止、出错或拒绝时队列暂停并提示继续或清空；
  • 按 clientRequestId 去重，重试不重复发送；
  • 只有档案与 agent 都声明支持（omp、Codex、Claude Code）且回合进行中时显示“插话”，OpenCode 没有插话；
  • Codex 与 Claude 的插话在回合已结束时返回 promptRequired（Claude 可为 noRunningTurn），这条消息排到队首作为下一回合发送，不产生 webmux 不知道的回合。
• US-Q09 聊天端提醒：作为离开页面的使用者，我希望聊天端的回合状态像终端会话一样提醒我，以便及时回来批准或继续。 验收要点：
  • 有待答复的权限请求为 permission、表单为 question，回合 end_turn 结束为 done，拒绝、错误或需要登录为 error，来源为 agent；
  • 发送或答复后清除；
  • 状态取 running/waiting/idle；
  • 现有 Web Push 照常推送，不新增通道；
  • 首页卡片标出所在端（终端、聊天、聊天·休眠、切换中），聊天端以最新 agent 消息（最多三行）代替终端预览，分组与排序不变。
• US-Q10 异常与登录：作为使用者，我希望 agent 进程意外退出或需要登录时得到确定的结果，以便知道下一步怎么做。 验收要点：
  • TUI 自行退出（含 /exit 与崩溃）时会话标记为已中断，保留最后终端输出并提供恢复到聊天或终端，不自动切换；
  • ACP 进程意外退出时当前回合以中断结束并自动重连一次（声明支持时用 session/resume，Claude 声明支持且恢复后重应用 model/effort、保留实际 mode），再次失败标记为已中断；
  • 切换回滚失败标记为已中断；
  • auth_required 结束回合并显示“切到终端登录”，聊天视图不执行登录；
  • Claude 复用 TUI 的服务用户、HOME、配置目录与现有订阅/API key/OAuth/provider 认证，不另存凭据，命令菜单隐藏 login/logout，也不提供其他聊天端登录或注销入口。
• US-Q11 空闲休眠与唤醒：作为部署者，我希望无人使用的聊天端会话释放 agent 进程，以便节省服务器资源而不丢失会话。 验收要点：
  • 聊天端没有回合、待答复请求与排队消息且 chatIdleSleepMinutes 分钟无命令时结束 ACP 进程并标记休眠，仍是运行中会话；
  • 打开聊天通道或提交命令时自动唤醒（支持时用 session/resume 保持事件连续，否则 session/load 并换代），休眠期间提交的消息在唤醒后发送；
  • 设置页可修改，默认 30、0 为不休眠，网页修改立即生效并在设备间同步。
• US-Q12 关闭后恢复：作为使用者，我希望关闭或因重启中断的混合会话之后还能接着聊，以便服务重启不再意味着失去 agent 对话。 验收要点：
  • 关闭混合会话把记录标为已关闭，服务启动时把活动记录改为已中断并结束 PID 与启动标识都匹配的残留进程组；
  • 首页底部“可恢复”分组默认折叠并显示数量，卡片优先显示持久化的当前会话标题（旧记录没有标题时回退到创建名称）、agent、目录、所在端、状态、时间与“上一轮可能未完成”“排队消息已丢失”提示，可恢复到聊天或终端（沿用原 ID）、确认后移除；
  • 原 agent 会话不存在时列出同目录候选，启动配置已删除时确认后不带环境变量恢复；
  • Claude 记录沿用 claudecode 档案与通用候选/外部占用错误，恢复聊天后重应用 model/effort 并保留实际 mode，注册记录不可读不伪造无外部写者保证；
  • 记录不含环境变量值、消息、注册记录正文或 token，存储不可用时只禁用混合会话。
• US-Q13 本地终端接入混合会话：作为原生终端使用者，我希望 CLI 对混合会话的行为清楚可预期，以便与 Web 端的切换配合使用。 验收要点：
  • webmux run --launch-config 引用混合配置时创建从终端开始的混合会话；
  • webmux attach 在会话处于聊天端、休眠或切换中时拒绝并以 1 退出，附着期间被切到聊天视为被动分离，恢复终端、提示后以 0 退出，切回终端不自动重新附着；
  • webmux ls 在状态列附加所在端，--json 原样包含 hybrid；
  • 本地终端不提供切换命令。
• US-Q14 聊天中上传素材：作为聊天中的使用者，我希望上传文件或图片作为下一条消息的附件，以便让 agent 获得素材而不用切回终端。 验收要点：
  • 聊天输入框的回形针、拖放到聊天视图与文件粘贴共用会话上传接口，多文件按顺序上传；
  • 上传中显示文件名、批次序号、百分比并可取消，期间禁用发送、插话与再次上传；
  • 完成后以可移除 chip 列在输入框上方，不改动草稿文本、不自动发送，只有附件时也可发送；
  • 单条超过 8 个、单文件超过 10 MiB 或合计超过 20 MiB 时上传前拒绝；
  • 上传与待发送附件属于会话页，Claude 与其他 agent 共用该状态，切换两端、休眠唤醒与自动重连不另建上传流程也不丢失待发送 chip，离开会话页中止上传，刷新页面后未发送的附件不保留；
  • 会话不存在或已退出时拒绝上传，取消或失败不产生伪造附件。
• US-Q15 聊天附件：作为聊天端使用者，我希望图片和文件随消息以 agent 原生内容发送，以便 agent 直接看到素材而不必自己读取路径。 验收要点：
  • 发送后用户气泡显示附件图标与文件名；
  • state.promptCapabilities 取自 ACP initialize，声明 image 时 PNG/JPEG/GIF/WebP 以 base64 image 块发送且字节一致，声明 embeddedContext 时其他附件以文本或 blob resource 块发送，否则按服务器路径降级并在时间线提示，图片能力不足时输入框提前提示；
  • Claude 连接器 0.99.1 声明图片与嵌入资源并复用同一管线，但不把该实测能力推广为未来 latest 或所有 MIME 类型的保证；
  • 队列条目跨设备带附件元数据，编辑文本保留附件，切到终端时附件路径并入退回的草稿，重启不持久化附件；
  • 只接受上传目录内、非符号链接的普通文件（临时目录本身可以是符号链接，如 macOS /var），单文件 10 MiB、单条最多 8 个且合计 20 MiB，越界或超限在读取前拒绝。
• US-Q16 第三方连接器安装提示：作为使用者，我希望在 agent 的聊天端需要另外安装的连接器缺失时得到明确的安装指引，以便知道该装什么而不是只看到“启动失败”。 验收要点：
  • 档案声明的连接器（Codex 的 codex-acp、Claude Code 的 claude-agent-acp）在每次启动 ACP 进程前（资格探测、从聊天开始、切到聊天、恢复到聊天、唤醒、重连）按启动配置的写法检查（直接执行查启动配置环境的 PATH，“加载 shell 启动文件”经同一 Bash/Zsh 包装执行 command -v）；
  • 未安装时不启动 ACP 进程，返回 409 connector_missing 并附 {executable, title, installCommand, docsUrl}，从聊天开始不创建会话与记录；
  • 终端端照常使用；
  • 会话页禁用“聊天”并显示对应“未安装 Codex ACP 适配器（codex-acp）”或“未安装 Claude Code ACP 适配器（claude-agent-acp）”与可关闭的安装提示条，安装后 30 秒内自动重新检测；
  • 新建会话弹层在“从聊天开始”旁预先说明，失败时保留输入并提供“改为从终端开始”；
  • 聊天视图在唤醒或重连失败时显示安装提示与“切到终端”；
  • 设置页在 Codex 或 Claude 配置的勾选框旁显示可复制的安装命令与说明链接；
  • Claude 明确要求 Node.js 22+，安装命令 npm install -g @agentclientprotocol/claude-agent-acp 跟随 latest，实测 Claude Code 2.1.316/连接器 0.99.1 只作版本提示而非最低版本或未来兼容承诺；
  • webmux 不自动安装连接器或 Node，也不用 npx 临时下载。

依据：

• 混合会话服务、连接器检查、agent 适配器核心、ACP 客户端
• agent 注册表、Codex 适配器、适配器契约测试
• Claude Code 适配器、Claude 注册记录
• 会话外壳与伴随进程、进程事实、聊天接口、聊天通道
• 启动配置、聊天视图、会话页
• 可恢复分组、安装提示、原生附着、使用说明、协议、端到端测试。