cdp_hub/docs/tasks/T-305.md

---
id: T-305
title: GUI 受管实例优雅停止与启停状态机
phase: 3
deps: [T-304]
status: DONE
created: 2026-07-25
owner: 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` 均通过。
- 阻塞：无。