持续优化 Web 使用体验：设置、浏览器、文件与会话交互

[testikun]

目标

持续优化 OpenPI Web 的日常使用体验，围绕真实使用中的“输入 → 发送 → 查看执行与文件变化 → 切换会话 → 取消或恢复”闭环，按可复现的小批次修复交互与生命周期问题。

Related to #455。#455 保持总体体验入口；本 Issue 聚焦 PR #561 合并后的使用测试与迭代，不重复建设已完成的工作栏、设置页、终端或浏览器功能。

当前已确认的问题

基于 PR #561 的真实 Web 实例和两轮确定性回归，发现以下需要继续修复的场景：

1. 图片仍在读取时可以发送文字，导致待导入图片漏发。
2. 图片读取期间切换会话，迟到结果可能进入另一会话的草稿。
3. 内嵌浏览器不能粘贴文本，Shift+Tab 又丢失 Shift 状态，影响表单填写和反向导航。
4. 分栏手柄只能使用指针，键盘用户无法调整阅读区域。
5. 切换会话后可能继续显示上一会话的 Git 文件变化，迟到响应或失败路径会扩大误导。
6. Diff 自动刷新可能抢走主输入框焦点，中断正在编辑的草稿。
7. 终端输入排队期间发生失败、断连或组件卸载，尚未发送的命令仍可能继续派发。
8. 文件引用校验过程中无法点击取消；会话改变或对话框卸载后的迟到结果可能继续插入引用。

另发现的“Session 切换或清理后仍创建旧 PTY”已由 #561 最终合并版本修复。本轮沿用主分支实现，补充排队、加载、切换工作目录及清理边界测试，不重复替换实现。

以上是已经复现的问题或已合并的修复事实；更广泛的移动端、输入法、长期断线和性能体验属于后续调查方向，不视为当前已证实缺陷。

迭代方式与边界

• 以真实使用场景为入口，记录操作步骤、预期行为、实际结果及运行版本；对竞态使用可控延迟测试固定证据。
• 优先处理误发、跨会话混淆、取消后继续执行、焦点中断，再处理操作反馈与视觉细节。
• 保持 Pi 对 Session、模型、配置、权限和工具执行的所有权；复用现有 WebHost 与组件生命周期，不增加第二套会话或编排系统。
• 每批修复给出清楚的范围、回归测试和真实浏览器复测；尝试移除不必要的状态和抽象。
• 延续 迭代 Web 体验，修复日常使用 bug 并完善子代理查看 #559 / feat(web): 打开子代理任务并查看真实执行过程 #560 的工作记录，不改写已有结论，不公开密钥、私人 Session 或本地原始配置。

本轮验收标准

• 图片导入完成后才能提交；取消或切换会话后的旧结果不能污染当前草稿。
• 内嵌浏览器支持受限文本粘贴并正确传递 Shift；分栏可通过键盘操作。
• Git 变更只对应当前选中会话；Diff 刷新不打断正在输入的内容。
• 终端停止、断连或失败后不继续派发未发送的输入；创建与清理边界有回归覆盖。
• 文件引用校验可取消，且迟到结果不插入、不遗留 artifact handle。
• bun run check、bun run test 与 Chromium 端到端测试通过；明确记录真实模型与真实 PTY smoke 的结果和局限。

本 Issue 用于持续跟进，首个修复 PR 完成上述批次后更新状态；尚未验证的后续方向单独复现、评估和拆分，不由一个 PR 宣称全部解决。

本轮进展

前两轮修复已合并到同一个 PR：#598，由 @testikun 提交，已推送，待 Review / 合并。本轮不再拆分多个 PR。

初始整合时（2026-09-20），在已合并 #561 的 main 上，bun run check 通过；Node 1703 passed / 1 platform skip，Vitest 309 / 309，Chromium 端到端 52 / 52。两个源码研究记录保留复现步骤、消融、真实模型与 PTY smoke 以及验证局限：

• 第一轮：图片、浏览器输入与键盘分栏
• 第二轮：会话隔离、焦点与异步取消

已在本 Issue 留言认领；当前账号无权修改仓库 Assignee 字段，需维护者设置为 @testikun。实现和提交不受此字段限制。

2026-09-21 更新：同一 PR 的后续使用迭代

所有修复继续集中在 #598，最新提交 4d229e5，没有拆分新的 PR。

• 设置与思考菜单在第一次发消息之前即可使用，保留草稿；headless 会话不再为未使用的搜索工具等待二进制下载。
• 设置页可添加/编辑自定义模型、保存 API Key；写入 Pi 原生配置/凭据。OpenPI 自有设置、子代理角色与并发、技能及插件需求仍统一通过 /openpi-setup，密钥不会进入模型对话。
• 浏览器改用 DPR 感知的 PNG screencast，限制帧积压、合并滚轮输入，并正确跟随面板尺寸。
• Git 默认使用未暂存状态，提供暂存/分支范围并按需读取文件差异；大未跟踪文件不再让整页依赖基线捕获失败。会话基线不可用时给出可操作说明。
• 跨 worktree 的原生编辑记录可查看；外部文件需显式授权只读打开单个文件，支持后续刷新，不扩大目录权限。

参考调查覆盖 Codex 官方 Review、Claude Checkpointing，以及固定版本 Maka、两种 Pi Web 和 Chromium 实现；结论、范围、消融与证据边界保存在 原生 Web 交互调查记录。

最新验证：bun run check 通过；Node 1711 passed / 1 Windows-only skip，Vitest 317 passed，生产构建 Chromium E2E 54/54 passed。独立实例验证模型/测试密钥保存与 setup 表单；真实 Chromium 验证 2x PNG 视口及输入坐标。均不是通用性能 Benchmark，也未声称覆盖所有超时原因。

用户正在使用的 57161 常驻实例未更新或重启；测试服务和临时测试页已关闭。后续未验证体验仍留在本 Issue 持续跟进。

2026-09-21 第三轮：五项交互与响应问题

继续集中在 #598，提交 c781376：

1. 模型配置输入未保存时，切换设置标签会清空表单；现保留同一 Session 下的编辑草稿。
2. 相同 Git revision 的摘要刷新会重复读取选中的 diff；现只在版本、文件或读取目标变化时重新读取。
3. 裸写本地浏览器地址被补成 HTTPS；现正确选择 loopback HTTP，并保留端口和显式 HTTPS。
4. Control/Command 全选、撤销等编辑组合键被前端忽略；现转发修饰位并使用原生 CDP 编辑命令，粘贴仍走宿主剪贴板路径。
5. 主机响应慢时鼠标移动持续排队；现限制为一个在途请求和最新位置，关闭工具后丢弃未发送位置。消融移除了多余的 60ms 等待，相关测试仍通过。

修复前新增用例有 6 条失败（Control/Meta 分别覆盖），修复后通过。最终 bun run check 通过；Node 1711 passed / 1 Windows-only skip，Vitest 329 passed，生产构建 Chromium E2E 56/56 passed。

真实 Chromium 用例验证本地 HTTP 页面、全选替换与撤销，并读取外层 UI 已显示 PNG 的像素确认画面改变。两次本机按键到画面更新上界样本为 151ms 和 123ms，含自动化及轮询开销，不作为通用性能保证。完整复现、消融及证据边界。

57161 常驻实例仍未更新或重启。配置归属与 /openpi-setup 入口保持原有约定。

2026-09-21 第四轮：保存反馈、键盘与拖拽

已继续提交到同一个 #598，提交 ece3e42。本轮五类修复：

1. 修改模型数值、API 或推理开关后，旧“已保存”提示没有清除。
2. 配置冲突后的刷新只更新 revision，表单仍显示旧值，重试可能覆盖外部修改。
3. 切换服务商后，旧服务商保存请求的迟到回执显示在新服务商下。
4. 设置标签没有方向键/Home/End 导航，也没有单一 Tab 焦点入口。
5. 内嵌浏览器拖出面板后丢失 mouseup，右键被当作左键，拖拽按钮状态不完整。

修复前 7 条设置用例、2 条鼠标用例失败；真实 Chromium 越界拖拽也复现失败。修复后 bun run check 通过，Node 1711 passed / 1 Windows-only skip，Vitest 338 passed，生产构建 Chromium E2E 56/56 passed。

独立 57461 实例确认：方向键切换生效，编辑即清除成功提示，外部修改后能载入最新字段值。真实 Chromium 验证越界松开和右键身份。测试页与测试服务已关闭，57161 常驻实例未更新或重启。

第四轮复现、消融与验证记录。持续优化目标保持开放；没有把本轮五类修复解释为所有 UI 问题已经清除。

2026-09-22 第五轮：侧栏、图片、设置与回合反馈

继续集中在 #598，最新提交 fbf15d2；已合入 main 6132d99（合并提交 d9568c4），保留上游会话 ID/路径校验和前台 post-edit 生命周期。

• Git、diff、子会话和文件记录减少隐藏面板中的重复工作；Git 一次只保留一个在途读取，并在打开面板时提升刷新优先级。
• 长会话标题使用紧凑单行显示。已授权的 PNG/JPEG/GIF/WebP 支持内容预览；相同内容不重复下载，撤销或关闭释放资源。
• 混合文字/图片粘贴保留原生光标与撤销，图片顺序有界导入；首次创建会话只按精确创建回执迁移待导入图片，跨会话仍取消。
• 设置模型树驱动编辑对象并保留草稿；窄屏使用带文字的分类选择器，补齐尺寸重置、键盘导航和忙碌反馈。所有 OpenPI 自有设置继续走 /openpi-setup。
• 配置操作、结果、错误不再被隐藏；新增 setup episode 明确区分历史关闭回执。运行中显示已处理时间，结束后显示用时；来自 Pi 实际生命周期并保存到原生 Session。
• / 菜单开放原生 setup 与现有 Web 面板快捷入口，其他命令显示不可用原因。参数不适用时保留草稿并说明。

验证：bun run check；Node 1856 passed / 1 Windows-only skip，Vitest 417 passed，生产构建 Chromium E2E 61/61 passed。真实 UI 完成配置保存及25秒耗时显示；独立采样确认连续 setup 正确重新暴露 writer，澄清提示后的两次真实配置各应用一次并保存。该样本不代表普遍模型可靠性；曾观察到的未应用结果与正反证据均保留在记录中。

第五轮复现、消融、参考与验证边界。原始截图和日志单独归档，凭据与私有 Session 不进 Git。57161 常驻服务未更新或重启，独立57561测试服务已在空闲时关闭。

持续优化仍在进行；下一批优先修复长会话历史缺页、正文阅读排版，并复现侧边对话导航、终端焦点和文件预览关闭状态等候选；执行过程区域保持原设计，未验证项不提前记为已解决。

2026-09-22：历史阅读、后台进度和输入控制

继续集中在 #598，提交 2f78cf3；main 6132d99 已包含在分支内。本轮补齐以下实际使用问题：

• 长单轮产生超过250条记录或2MiB输出后，旧用户消息会被初始快照省略；新增有界历史分页与阅读锚点，旧分支迟到页不会进入当前视图。
• 正文改进段落、列表编号、行内代码与文件链接；保留已有字号设置和执行过程设计。
• 后台Session继续工作但不推送进度、旁观又误用当前控制者的idle状态；现独立投影所看Session，保存/恢复原有取消与计时身份，并复用原生manager避免反复解析文件。
• 同文输入被一次清空、直播缓存挤掉待处理项、刷新抢回其他会话、关联记录离开窗口后旧消息回漂；现按scope、实际准入、原生边界和队列下限保守处理，展示关联不被当成执行回执。
• 同ID复制文件可能出现另一会话的停止控件；输入控制使用原生ID和文件路径，旁观提供明确激活入口。运行中可分别选择发送或停止，旁观隐藏另一控制者的模型与旧回执。
• 侧边导航被迟到结果覆盖、终端连接/重启抢焦点、预览自动关闭后外层状态残留，以及浏览器退出信号误报启动超时，均有失败回归及修复。

最终本地验证：bun run check通过；Node 1869 passed/1平台skip，Vitest459 passed，真实Chromium E2E65/65 passed。SDK与HTTP的双Session浏览器场景确认A继续显示进度，停止只影响A、B继续运行。读历史锚点偏移≤2px。远端CI将按新提交重新运行。

完整证据、消融、边界与SDK关联限制。原始证据在私有round6归档，凭据和用户Session不进Git。

用户57161常驻服务未更新、重启或中断。其GitHub连接超时与启动环境的代理差异相关，未擅自修改用户Git或代理配置；这与已修复的后台UI状态盲点分开记录。本Issue继续开放，不声明所有Web问题均已消除。

2026-09-22 收尾验证

同一 PR #598 已推送历史/输入修复 4e9ba87、启动诊断 0b5a0f2 和关闭清理修复 4480b8d，继续保留 main 6132d99。

• 外部标签页切换输入控制者时，保留当前历史阅读视图、旧消息和滚动锚点；身份刷新期间不允许误发。真实 App、Store 与历史 hook 集成回归及权限消融通过。
• 浏览器迟到的初始状态及打开/刷新回执不会覆盖新编辑的网址；五项专项场景通过，去掉保护后四项准确失败。
• CI 的原生文字拖放与普通鼠标拖动分开验证。保留 Linux 原生 Chrome sandbox；Windows 完整套件按实测持续时间保留十分钟上限，进程组仍隔离。
• 新增 Linux 冷启动门禁抓到 ENOTEMPTY：发送结束信号后就删除目录，而 Chromium 仍在写文件。现在等待原生 close 后清理目录，保留有限清理重试；原始启动失败不再被次级清理错误覆盖。旧实现两项真实进程回归失败，新实现通过。
• 启动期保留最多4KiB诊断到宿主日志，成功后释放，HTTP不暴露原始stderr。另一例八秒端口等待超时的历史根因仍未确认，不把清理修复当作已经证明的唯一原因。
• 当时本地 bun run check 通过；Node 1873 passed / 1 skip、Vitest 465 passed、生产构建 Chromium 65/65 passed。该次 CI 的 Linux 冷启动与 Web E2E 通过，另外两项失败来自 React 效果未就绪和 POSIX/Windows 管道语义不同的测试前提，随后在 13465ad 修正，保留实际输入断言及所有平台的原生进程关闭覆盖。
• 代理配置只准备了未应用候选；后续相同只读命令对照中，原环境约2.97秒、候选约1.70秒均能连接 GitHub。因此代理差异不能确定为此前超时的唯一根因，更不是已经验证的永久修复。原 plist、57161、用户 Git 配置均未改动。

原始复现、失败日志、消融与最终验证在原 round6 私有证据目录追加归档；公共结论仍见历史与生命周期记录。

2026-09-23：同步最新 main 并完成集成验证

所有变更仍在 #598，最新提交 0bc3470，已合入实际 main 43cd2e9。保留结构化问答、计划卡片、原生命令反馈、配置诊断/回滚、锁恢复、工作区准入后身份复查、Windows PTY、工作流产物预算及会话日期等主线变更。

• 计划修改使用 Session ID＋原生路径；旧回执不能清除重新取得控制后的新请求状态。移除回执归属保护会准确触发回归失败。
• /usage 走主线原生命令反馈，其他面板快捷入口保留；setup 原请求与结果仍显示，问答卡片只允许原控制标签提交。
• 原生历史 entryId 与 React 渲染 key 分离；缺少消息身份的旧事件按一对一匹配，不再产生重复用户气泡。
• 低高度窗口的发送按钮保持在视口内，命令菜单按实际空间上下摆放，执行详情可用键盘滚动。

最新本地 bun run check 通过；Node 1925 passed / 5 skipped，Vitest 497 passed；默认真实 Chromium E2E 65/65，Pi SDK＋脚本化 provider 的问答/计划/命令 E2E 12/12。脚本化 provider 不作为真实模型能力证明。最终提交 CI 已全部通过：Node 22.19.0 / 24 / 26、Linux Web E2E（含三次独立 Chromium 冷启动与清理）、Windows 原生进程和完整套件。PR 无冲突；工作区已提交干净。

该轮验收时，57161 仍为 6c58e98、PID 1113，未部署或重启。曾阻断完整测试的自动审批服务已恢复，测试已实际执行；没有绕过审批或把未执行命令记为通过。

2026-09-23：PR 复审问题修复

继续提交到 #598，提交 81d4c67：

• 逐文件详情先通过完整 raw diff 找到 rename 的旧/新路径，再以字面 pathspec 读取，两端不再丢失。覆盖纯 rename、rename 后编辑、分支比较和含方括号的文件名。
• 摘要 revision 纳入所比较 Git 对象、文件模式与路径身份。只改 index blob、工作文件及其元数据完全不变、+/- 统计相同的情况下，staged 和 unstaged 都能产生新的 revision；HEAD 对象变化也有覆盖。
• 新增真实 Chromium＋WebHost＋Git 场景，确认旧路径在详情中可见，以及保留选中文件、草稿和焦点时能刷新 index-only 修改。
• 滚轮用例已在 13465ad 等待 React 被动效果，当前修复没有撤掉断言。本次继续等待新提交 Node 24 和完整 CI，不拿旧版本的绿色结果替代。

六项真实 Git 回归在原 head 上全部失败，修复后 Git review 15/15 通过；分别移除路径与对象身份保护，回归再次失败。完整本地检查通过，Node 1931 passed / 5 skipped、UI 497 passed、真实 Chromium 66/66 passed。

81d4c67 的 Node 24 等 Node/Windows 检查通过，Web 任务在用例运行前的冷启动门禁失败，诊断给出无效 D-Bus 地址。250731f 为 Linux CI 提供隔离会话总线；保留三次启动的失败、原超时和 sandbox。最新 CI 已全部通过：Node 22/24/26、三次 Linux 冷启动及清理、Web E2E 66/66、Windows 进程生命周期和完整套件。当前 Node 24 的完整测试包含原滚轮回归。

复现、消融和验证边界。原始证据保存在私有 openpi-pr561-usage-20260920/git-review-20260923。常驻 57161 此前已按用户要求更新到 0bc3470；本次 Git 修复未重启该实例。

[testikun]

我来认领本 Issue 的本轮实现与回归验证。

计划将 PR #561 之后已完成的两轮使用测试结果整理为独立 PR：保留最新 main 已合并的 PTY 创建取消实现，提交其余输入、会话隔离、浏览器键盘、分栏、Diff 焦点、终端输入队列和文件引用修复，并补充针对失败、取消和迟到结果的测试。

会在新 PR 中关联本 Issue、附上可复核的研究记录，并在最新 main 上重跑仓库检查、完整测试和浏览器回归。本次认领范围为这批具体问题，后续未验证方向继续在本 Issue 中跟进。

[testikun]

PR #598 now includes commit 94059b5 for per-user-turn change cards, Codex-inspired native history/item pagination, and explicit recovery of truncated visible message bodies. The cumulative composer file bubble is removed. The older-reading-window duplicate-input regression and narrow-screen jump control are covered.

Local verification: bun run check, bun run test (Node 1,948 pass / 5 skip; Vitest 498 pass), and full Chromium E2E 67/67 pass. GitHub CI is pending. No restart or deployment to the resident 57161 service was performed.

Reusable conclusion, evidence boundaries, and ablation: https://github.com/testikun/openpi/blob/codex/web-ux-597/docs/research/WEB_TURN_EVIDENCE_AND_ITEM_RECOVERY_2026-09-23.md . Turn diffs are temporal Git comparisons, not proof of the writer; old Sessions are not backfilled and unavailable or quota-limited baselines are marked explicitly.

[testikun]

Validation follow-up for PR #598 commit 94059b5: the full CI run is green across Node 22/24/26, Linux Web E2E, and Windows background terminals: https://github.com/openpi-dev/openpi/actions/runs/35840808353 . This supersedes the pending-CI status in the prior update; the resident 57161 service has not been restarted.