---
id: T-303
title: 实例状态刷新与编辑对话框
phase: 3
deps: [T-302]
status: DONE
created: 2026-07-25
owner: codex
---

## 需求与背景

实例页需要把“新建实例”与“刷新实例状态”作为同一命令区的两个等宽操作：默认窗口下各占可用宽度的 50%，窄窗口自动堆叠。刷新需要重新检查已保存且用户已授权的实例状态，而不是扫描或控制系统中所有 Chrome/Edge。

用户双击实例列表记录时需要打开实例编辑对话框，查看和修改名称、浏览器类型、User Data Dir、启动 URL 等保存配置；目录字段需要继续使用 Windows 原生目录选择器。对话框必须支持保存、取消和 Escape 退出，且不应静默丢弃已修改内容。

## 方案与边界

- UI 增加集中管理的异步 `InstanceRefresher` 回调和结果通道。刷新操作只针对当前保存的 `InstanceRow` 快照；后台依次检查 Chub registry、该行规范化 User Data Dir 的外部占用证据和已知的 loopback CDP 端点，不枚举全局进程名或端口。
- 刷新期间禁用刷新命令并显示“刷新中…”。成功后更新行的状态、PID、实际关联端口和来源；删除或编辑后到达的过期结果不得覆盖当前行。刷新失败保留上次有效行状态，并给出非模态反馈。
- 运行时端口是启动时由全局“远程调试起始端口”分配的实际值，编辑对话框以带 Label 的只读字段展示，不作为每实例持久化配置。若未来需要固定端口，必须另行设计端口保留、冲突与重启策略。
- 双击行或按 Enter 打开编辑对话框；单击只设置当前行。为避免把双击作为唯一入口，行操作区增加独立的编辑图标。启动、删除和编辑图标消费各自输入，不触发行的默认操作。
- 编辑对话框保存名称、浏览器类型、User Data Dir 和启动 URL；字段有 Label、邻近帮助文本和就地校验。目录选择器回填输入框。保存时复用实例变更回调，保留配置中未由此对话框编辑的 profile、代理、headless 与额外参数。
- 对“启动中”“运行中”“外部已关联”实例不允许修改浏览器类型和 User Data Dir，避免配置与正在运行的浏览器身份不一致；外部关联始终不取得生命周期控制权。
- Escape 在未修改时等价于取消；有未保存修改时先显示“保存 / 不保存 / 继续编辑”确认。对话框打开时焦点位于实例名称，关闭后焦点返回调用行；F5 触发状态刷新。
- Gio 的 `Clickable`、`Editor`、焦点恢复对象、编辑快照和脏状态均由 `Shell` 持久持有；所有检查和目录选择均在 UI frame 外执行。

## 验收要点

- 宽窗口中“新建实例”和“刷新实例状态”各占命令区一半；`<=640epx` 时纵向堆叠，按钮仍可键盘与触控访问。刷新按 F5 和按钮均可触发，同一时间只运行一个刷新任务。
- 刷新仅检查 Chub 配置中的行，能更新托管运行、已退出、外部已关联、外部/未知占用和调试不可用状态，以及 PID、端口和来源；不执行全局 Chrome/Edge 扫描、关闭或接管。
- 双击任一行、按 Enter 或点击编辑图标均打开对应编辑对话框；启动和删除图标不会误开对话框。
- 编辑对话框显示名称、浏览器类型 RadioButton、User Data Dir 输入/选择、启动 URL、只读实际调试端口和状态说明。有效保存后列表和本地配置更新；取消或 Escape 不修改数据；有未保存修改时不静默丢弃。
- 活跃或外部关联实例的受身份约束字段不可编辑且有恢复说明；删除仍只删除 Chub 配置，不删除 User Data Dir。
- 覆盖刷新成功、部分失败、重复刷新、行被删除后的过期结果、目录选择取消、字段校验失败、保存失败、仅键盘操作和窄窗口布局。
- `gofmt`、`go test ./...`、`go vet ./...`、`go build -o build/chub.exe ./cmd/chub`、`scripts/smoke-browser.ps1` 与 `scripts/smoke-windows.ps1` 通过。

## 执行记录

- 状态：DONE
- 变更：Gio 实例页新增等宽“新建实例 / 刷新实例状态”命令区，窄内容区自动纵向重排；刷新通过异步 `InstanceRefresher` 只检查已保存实例，并以可编辑字段快照过滤已删除或编辑行的过期结果。Windows adapter 按 Chub registry、指定 User Data Dir 的外部占用证据和已知 loopback CDP 端点更新运行、调试不可用、外部关联、外部占用、未知占用或已退出状态，不扫描或接管其他浏览器。列表新增独立编辑图标、双击和 Enter 编辑入口；编辑弹层支持名称、浏览器 RadioButton、User Data Dir 选择、启动 URL、只读实际端口、保存/取消/Escape 与未保存更改确认。运行中、启动中、调试不可用和外部关联实例锁定浏览器类型及 User Data Dir。
- 验证：`gofmt -w cmd/chub/main.go cmd/chub/main_test.go internal/ui/shell.go internal/ui/shell_test.go`、`go test ./...`、`go vet ./...`、`go build -o build/chub.exe ./cmd/chub`、`scripts/smoke-browser.ps1`（真实 Chrome/Edge）和 `scripts/smoke-windows.ps1` 均通过。
- 阻塞：无。