docs: define preferred debug port allocation

docs/02-requirements.md

@@ -17,6 +17,7 @@
 | BR-013 | 用户可以刷新已保存实例的状态，并编辑未运行实例的名称、浏览器类型、user data dir 和启动 URL；刷新和编辑不得扩大到未授权的浏览器进程。 | P1 |
 | BR-014 | 用户可以在完整代理地址下拉框中维护无认证代理，并在创建或编辑实例时选择代理；代理认证信息不得保存、记录或进入启动参数。 | P1 |
 | BR-015 | GUI 实例主操作在 Chub 托管运行态提供优雅停止、在可启动状态提供启动；外部关联或未知外部实例不得获得生命周期控制。 | P1 |
+| BR-016 | 每个已保存实例有独立、持久化的首选远程调试端口；它与运行时实际端口分离，未启动实例仍可在列表看到建议端口。 | P1 |
 
 ## 验收标准
 
@@ -28,6 +29,8 @@
 - 关闭操作不会影响其他 Chrome/Edge 实例。
 - 工具重启后，无法确认身份的外部进程只能报告 UNKNOWN，不得被关闭。
 - 异常退出后状态在合理时间内变为 EXITED/FAILED。
+- 新建实例从全局起始端口推荐一个未被其他 Chub 实例逻辑预留或实际使用的首选端口；启动优先使用它，并在后台复检 loopback 可用性与 CDP 端点。
+- 外部端口冲突时只能回退到未被其他 Chub 实例预留的端口；成功验证后更新当前实例首选端口，失败或外部关联不得改写配置。
 - 参数中不出现密码、Cookie、Token 或代理 userinfo。
 - UI 覆盖加载、空、占用、启动失败、关闭中、成功和权限错误。
 - 刷新仅检查 Chub 已保存的实例；任务执行中不可重复触发，过期结果不得覆盖已经删除或编辑后的记录。

docs/04-architecture.md

@@ -31,7 +31,7 @@ UI/CLI 不直接操作 `exec.Cmd`、Win32 handle 或数据库。Application 层
 
 `CREATED -> STARTING -> RUNNING -> STOPPING -> EXITED`；启动失败为 `FAILED`，无法确认的外部实例为 `UNKNOWN`。
 
-- Start：规范化路径和参数，先检查 user data dir。未占用时从配置的起始端口选择可用 loopback 端口，注册 pending 后以受控的 `--remote-debugging-address=127.0.0.1` 和 `--remote-debugging-port` 启动，并直接请求该已知端口的 `/json/version` 验证实际端点。
+- Start：规范化路径和参数，先检查 user data dir。未占用时优先从实例持久化的首选端口分配；UI 在启动快照中提供其他 Chub 实例的逻辑预留/实际端口，启动器跳过这些端口后检查 loopback 可用性。注册 pending 后以受控的 `--remote-debugging-address=127.0.0.1` 和 `--remote-debugging-port` 启动，并直接请求该已知端口的 `/json/version` 验证实际端点；发生外部端口冲突且回退成功时才更新当前实例首选端口。
 - 外部关联：目录被占用时只检查该目录中的 `DevToolsActivePort` 和其 loopback `/json/version`；端点与浏览器类型均匹配才报告 `EXTERNAL_ASSOCIATED`，不注册、关闭、重启或强制终止该 PID。无法验证时保持 `UNKNOWN`/占用并拒绝启动。
 - Stop：校验身份，优先窗口关闭/浏览器协议，超时后经明确授权强制终止。
 - Force stop：使用实例 Job Object 或已校验进程树，不按名称全局终止。

docs/06-tasks.md

@@ -44,6 +44,7 @@
 | T-306 | 精简代理下拉编辑与实例行安全操作布局 | T-304,T-305 | DONE |
 | T-307 | 受管浏览器意外退出监控与状态提示 | T-101,T-305,T-306 | DONE |
 | T-308 | 设置页分区与控件边框层级 | T-306 | DONE |
+| T-309 | 实例首选调试端口与安全推荐分配 | T-302,T-303,T-308 | DOING |
 
 ## Backlog
 

docs/07-user-stories.md

@@ -8,7 +8,7 @@
 | US-004 | 用户可以优雅关闭实例；无响应时在确认后强制终止。 | P0 |
 | US-005 | 用户可以重启指定实例，并确认旧实例已经退出。 | P0 |
 | US-006 | 用户可以通过 CLI/API 查询、启动和关闭实例。 | P1 |
-| US-007 | 用户可以看到实例关联的本地调试端口；同目录外部浏览器已启用调试时，Chub 只关联并展示状态。 | P1 |
+| US-007 | 用户可以看到实例的首选或实际本地调试端口；同目录外部浏览器已启用调试时，Chub 只关联并展示状态。 | P1 |
 | US-008 | 用户可以刷新已保存实例的运行状态，并通过对话框编辑非运行实例的基本配置而不影响其他浏览器。 | P1 |
 | US-009 | 用户可以在设置中通过完整代理地址下拉框维护无认证代理，并在新建或编辑实例时从下拉选择器选择代理。 | P1 |
 | US-010 | 用户可以通过实例行的同一主操作启动或优雅停止 Chub 托管的浏览器，而不会关闭外部浏览器。 | P1 |
@@ -30,7 +30,7 @@ CLI/API 返回稳定错误码和结构化数据；未知 PID、身份不匹配
 
 ### US-007 本地 CDP 与外部关联
 
-给定未占用的 user data dir，启动时从设置中的起始端口分配一个 loopback CDP 端口，并显示实际端口。给定同目录已由外部浏览器占用，只有 `DevToolsActivePort` 与 `/json/version` 可验证时才显示“外部已关联”；否则拒绝第二次启动。无论哪种外部状态，Chub 都不提供生命周期控制。
+给定未占用的 user data dir，实例先保存一个首选 loopback CDP 端口；新建时从设置中的起始端口推荐一个不与其他 Chub 实例预留或实际端口冲突的值。启动优先使用该端口，并在后台检查实际可用性；若仅外部端口冲突，跳过 Chub 预留端口后回退到下一个可验证端口并更新当前实例的首选端口。列表区分建议、准备、实际和外部端口。给定同目录已由外部浏览器占用，只有 `DevToolsActivePort` 与 `/json/version` 可验证时才显示“外部已关联”；否则拒绝第二次启动。无论哪种外部状态，Chub 都不提供生命周期控制。
 
 ### US-008 刷新与编辑实例
 

docs/08-interaction-checklist.md

@@ -12,6 +12,7 @@
 | IX-008 | 代理设置与选择器 | 完整地址下拉选择、新增/更新、删除确认；创建/编辑实例选择代理 | 空列表、无代理、格式错误、重复地址、删除取消、被引用删除、保存成功 | P1 |
 | IX-009 | 实例主启停操作 | 主操作、编辑、删除的固定顺序与间距；启动图标、停止图标、外部重新检测 | 已退出、启动中、托管运行、停止中、失败恢复、外部关联 | P1 |
 | IX-010 | 受管浏览器退出提示 | 受管根进程退出后的状态恢复、提示队列和焦点回归 | 意外退出、Chub 请求停止、多个同时退出、过期事件、编辑/确认弹层打开、应用关闭 | P1 |
+| IX-011 | 实例首选调试端口 | 新建/编辑端口推荐、列表建议/准备/实际/外部文案、启动回退与保存 | 旧配置迁移、重复/非法端口、外部冲突、启动失败、外部关联、过期结果 | P1 |
 
 ## 通用规则
 
@@ -27,3 +28,4 @@
 - 代理选择器必须提供“无代理”和完整地址项，能用键盘选择；设置页默认输入为空，选择项回填地址。删除前先确认完整地址；有引用时保持当前选择、输入与实例选择不变。
 - 实例主操作根据归属和状态切换启动、停止、重新检测或禁用，并固定排在编辑和删除之前。停止中禁止重复请求；停止失败恢复原状态并保留焦点。外部关联不显示停止入口；行内图标间距与命中区必须避免误操作。
 - 受管浏览器意外退出是当前会话的异步状态提示，不是用户确认决策：状态先更新为“已退出”，再显示可关闭信息弹层；弹层只含“知道了”，Escape/Enter 均可关闭，关闭后焦点回到对应启动入口。多个退出合并到一个提示；已有编辑、未保存确认或删除确认弹层时排队，不能丢弃输入或叠加模态层。Chub 发起停止、外部实例、代次/PID 不匹配和应用退出取消监控时均不提示。
+- 调试端口的“建议/准备/实际/外部”必须同时以文字和数值表达，不能将首选端口称为已监听端口。创建和停止实例编辑使用首选端口输入；运行中、启动中、停止中和外部关联实例只读。推荐仅基于 Chub 保存实例，系统端口复检与 CDP 校验只在后台启动任务执行；回退不得使用其他 Chub 实例的逻辑预留端口。

docs/current-state.md

@@ -2,14 +2,14 @@
 
 ## 快照
 
-- 日期：2026-07-26
+- 日期：2026-07-27
-- 阶段：Phase 3 真实实例操作（T-301 至 T-308、T-201 至 T-208 已完成）
+- 阶段：Phase 3 真实实例操作（T-301 至 T-308、T-201 至 T-208 已完成；T-309 进行中）
 - 代码：已建立 Go module `chub`、`cmd/chub` 入口、logging 测试基座、浏览器 domain/application 合约、Chrome/Edge 参数/发现模块、启动 registry、Windows 身份/占用检查、loopback CDP 端口分配与端点校验、优雅关闭、Job Object、真实 Chrome/Edge smoke、JSON 配置存储、启动恢复、CLI JSON 合约、应用内事件总线、UI 状态测试和 Windows smoke 脚本，T-001 至 T-003、T-101 至 T-104、T-201 至 T-208、T-301 至 T-307 已完成
 - UI：Gio 双页 Shell 使用左侧“实例/设置”导航；实例页以等宽“新建实例 / 刷新实例状态”命令区开始，窄内容区自动堆叠。列表固定显示实例名称、浏览器类型、用户数据目录、调试端口、状态和带边框的操作列；操作顺序固定为启动/停止（或重新检测）、编辑、删除，删除与相邻操作保持更大间距以降低误点。主操作在已退出时启动，在 Chub 托管运行或调试不可用时显示停止，在启动/停止中禁用，在外部关联、外部占用或未知占用时仅重新检测；优雅停止通过后台 adapter 验证 registry 的 PID/profile 身份并等待其释放，绝不按进程名关闭或接管外部 Chrome/Edge。刷新通过后台回调只检查已保存实例，以配置快照丢弃编辑或删除后的过期结果；它结合 Chub registry、指定 profile 的外部占用证据和 loopback CDP 端点更新状态，但不扫描、接管或关闭其他 Chrome/Edge。双击、Enter 或编辑图标打开实例编辑弹层，支持名称、浏览器类型、User Data Dir、启动 URL、完整地址代理选择和只读实际端口；保存保留未公开启动选项，Escape 对脏表单先请求确认，活跃/外部关联实例锁定身份约束字段。设置页使用完整代理地址选择器、地址输入及保存/删除操作；选择会回填地址，保存按稳定 `proxyId` 新增或更新，删除未引用代理前必须确认，仍被实例引用的代理会被拒绝。启动通过异步回调接到 Windows 浏览器启动器：未占用目录从已保存的起始端口（空值默认 9666）选择 loopback CDP 端口，并在启动时按已选代理 ID 解析最新的 `--proxy-server` 参数；同目录外部浏览器只有在 `DevToolsActivePort` 与 CDP 端点可验证时才显示“外部已关联”，且不会接管其生命周期。删除使用确认弹层，只删除 Chub 实例配置而不删除 User Data Dir。新建、编辑和删除实例会保存到本地配置；四个设置路径有独立异步可取消搜索，切换页面后输入和任务状态保留；新建实例表单使用 Label、Windows 原生目录选择器和 Chrome/Edge RadioButton；CLI `list/events` 已可用，`start/stop/restart` 等待 BrowserManager adapter
 - T-307：本应用会话启动的受管 Chrome/Edge 根进程由单实例后台 `Wait` 监控；意外退出按 ID、启动代次和 PID 验证后立即变为“已退出”，清空运行时 PID/端口，并以可关闭、可合并的提示告知用户。提示关闭后焦点回到启动操作；Chub 请求停止、外部实例、过期事件和应用关闭取消监控均不提示。
 - T-308：设置页以可滚动的外层工作区承载浏览器路径、默认目录、运行行为和代理分区；分区、字段、状态提示和保存操作区使用统一的浅色圆角描边。路径字段在紧凑内容区会将输入与“选择/搜索”操作纵向重排，切换页面后滚动、输入与异步搜索状态仍由持久 Gio widget 保留。
 - 浏览器核心：设计参考来自 `D:\OPC\shop_helm\internal\platform\chrome`，尚未复制或接入本项目
-- blocker：无；T-308 已完成，下一项从 Backlog 或后续需求确定。
+- blocker：无；T-309 正在为实例增加持久首选调试端口、列表建议状态与后台安全回退分配。
 
 ## 当前目录
 

docs/tasks/T-309.md

@@ -0,0 +1,39 @@
+---
+id: T-309
+title: 实例首选调试端口与安全推荐分配
+phase: 3
+deps: [T-302, T-303, T-308]
+status: DOING
+created: 2026-07-27
+owner: 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
+- 变更：待实施。
+- 验证：待执行。
+- 阻塞：无。