cdp_hub/docs/tasks/T-309.md

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

id	title	phase	deps	status	created	owner
T-309	实例首选调试端口与安全推荐分配	3	T-302 T-303 T-308	DOING	2026-07-27	codex

需求与背景

当前实例列表仅保存并显示浏览器正在使用的实际调试端口；实例未启动、停止或意外退出后运行时端口被清空，用户无法预知下次启动的 CDP 地址。启动器只从全局起始端口查找系统可用端口，无法将用户看到的端口与下次启动意图关联。

方案与边界

• 为每个已保存实例增加持久化 PreferredRemoteDebugPort（首选调试端口）。它是 Chub 的逻辑预留与下次启动优先值，不表示端口已经监听；现有 RemoteDebugPort 保持运行时实际端口，绝不持久化。
• 实例列表的“调试端口”列必须明确区分：未启动/已退出显示“建议 {port}”，启动中显示“准备 {port}”，Chub 托管运行显示“实际 {port}”，外部关联显示“外部 {port}”，无可验证端口继续显示“—”。不新增列表列，保持现有紧凑宽度。
• 新建实例时从设置中的远程调试起始端口开始，为新实例推荐最低未被其他 Chub 实例首选或当前实际端口占用的端口；创建表单可编辑该数值。编辑弹层允许停止实例修改首选端口，运行中/启动中/停止中/外部关联时只读；实际端口始终单独只读展示。
• 推荐完全基于 Shell 的已保存实例快照，不在 UI Frame 中探测系统端口或枚举 Chrome/Edge。启动后台任务收到其他 Chub 实例的逻辑预留端口集合，先尝试本实例首选端口，再跳过逻辑预留并调用 loopback 端口检查；CDP 端点校验仍是实际端口唯一事实来源。
• 首选端口因外部程序占用而回退至另一个可用端口并成功验证时，将该端口更新为当前实例的新首选端口并保存，同时给出清楚的非模态反馈。不得使用或占用其他 Chub 实例的逻辑预留端口。
• 旧 JSON 配置缺少该字段时，以配置中的稳定实例顺序从起始端口分配不重复端口；字段会在下一次配置保存时写入。手工配置中的非法或重复首选端口应被拒绝，不能静默覆盖。
• 端口仅限 127.0.0.1 和已有有效范围；本任务不扫描端口范围之外的系统浏览器，不接管外部浏览器，也不改变关闭/进程身份边界。

验收要点

• 新建、编辑、配置恢复和实例列表均保留并展示首选端口；停止与意外退出清空的只是实际端口，列表仍能显示下次启动建议。
• 新建推荐会跳过已保存首选端口与运行中实际端口；用户输入非法、重复或被另一实例预留的端口时，在字段附近给出恢复性错误并保留输入。
• 启动首先使用实例首选端口；若该端口被外部占用，后台选择下一个未被其他 Chub 实例预留的 loopback 端口，成功 CDP 校验后更新并持久化首选端口。启动失败、外部关联和未知占用不改写首选端口。
• 旧配置可确定地补齐缺失端口；配置读取/保存拒绝非法或重复端口，代理迁移与现有 JSON 兼容行为不回归。
• 新建/编辑的 Tab 顺序、Escape 取消、脏表单确认、行双击/Enter/编辑入口、紧凑宽度重排和实例行操作行为保持不变；HTML 原型与 Gio 实现使用同一“建议/准备/实际/外部”文案。
• 覆盖端口推荐、排除当前实例、旧配置迁移、配置重复拒绝、创建/编辑校验、列表文案、启动首选、跳过预留端口、成功回退持久化和过期启动结果；gofmt、go test ./...、go test -race ./cmd/chub ./internal/ui、go vet ./...、go build -o build/chub.exe ./cmd/chub、HTML 脚本检查和 scripts/smoke-windows.ps1 通过。

执行记录

• 状态：DOING
• 变更：待实施。
• 验证：待执行。
• 阻塞：无。