cdp_hub/docs/tasks/T-305.md

id, title, phase, deps, status, created, owner

id	title	phase	deps	status	created	owner
T-305	GUI 受管实例优雅停止与启停状态机	3	T-304	DONE	2026-07-25	codex

需求与背景

实例列表当前能异步启动已保存实例，但无法从同一入口关闭 Chub 启动的浏览器。用户需要启动按钮在可控运行态切换为停止图标，再次点击时请求浏览器优雅退出，成功后恢复启动图标。

方案与边界

• 复用实例行的主操作位：已退出、失败或可启动状态显示启动图标；Chub 托管运行/调试不可用状态显示停止图标；停止中显示不可重复触发的停止中状态；外部已关联继续显示重新检测，绝不显示生命周期控制。
• 停止请求通过 UI 持有的异步 InstanceStopper adapter 发出。adapter 只调用平台 StopProfile(userDataDir, false)，并依赖 Chub registry 的 PID、可执行文件和 user data dir 身份校验；绝不按 Chrome/Edge 进程名批量终止，也不对外部关联实例调用 Stop。
• 平台成功发出优雅关闭后等待有限时间观察注册实例释放。超时、身份不匹配或权限错误回到原运行状态并显示恢复建议；本任务不自动升级为强制关闭。
• 成功关闭后清空运行时 PID/端口、显示“已退出”、恢复启动图标并将键盘焦点留在同一行。操作状态同时使用图标、文字和禁用态，不只依赖颜色。

验收要点

• 受管运行实例的主操作为停止图标；点击后立即显示“停止中”，重复点击不会发出第二个停止请求；成功后显示“已退出”和启动图标。
• 外部已关联、外部占用和未知占用实例不能获得关闭入口；其主操作仅可重新检测或不可用。
• 停止 adapter 仅接收当前已保存实例行，校验失败、无注册记录、超时和权限失败均不会影响其他浏览器进程，且 UI 恢复到可理解状态。
• 覆盖成功关闭、失败恢复、重复点击、启动中、外部关联、调试不可用、刷新与停止结果竞争、键盘/触控访问和焦点恢复。
• gofmt、go test ./...、go vet ./...、go build -o build/chub.exe ./cmd/chub、scripts/smoke-browser.ps1 与 scripts/smoke-windows.ps1 通过。

执行记录

• 状态：DONE
• 变更：实例主操作现在按状态显示启动、停止、重新检测或禁用图标。受管运行/调试不可用实例点击停止后进入“停止中”，后台 adapter 先检查 Chub registry 来源和 PID，再调用 StopProfile(userDataDir, false)，等待 registry 释放后清空 PID/端口并恢复启动图标。超时、身份不匹配或权限失败保持原运行状态并给出反馈；外部关联、外部占用和未知占用只允许重新检测。停止期间拒绝重复启停和删除。
• 验证：gofmt -w cmd/chub/main.go internal/ui/shell.go cmd/chub/main_test.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 均通过。
• 阻塞：无。