cdp_hub/docs/tasks/T-302.md

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

id	title	phase	deps	status	created	owner
T-302	本地 CDP 启动、外部关联与实例端口展示	3	T-102 T-301	DONE	2026-07-25	codex

需求与背景

Chub 需要为新启动的 Chrome/Edge 分配仅限 loopback 的 remote debugging port；设置中的起始端口留空时使用 9666。实例列表需要展示实际关联端口并使用清晰的边框分组。

如果其他程序已经使用同一规范化 User Data Dir 启动浏览器，Chub 不得再次启动同目录浏览器。只有该目录中的 DevToolsActivePort 与 127.0.0.1:<port>/json/version 可验证为同类浏览器时，Chub 才能将其标为“外部已关联”；此关联不赋予关闭、强制关闭、重启或其他 CDP 页面控制权限。

方案与边界

• LaunchSpec 将 remote debugging port 作为受控领域字段；BuildArgs 固定生成 --remote-debugging-address=127.0.0.1 和 --remote-debugging-port=<port>，额外参数继续不得覆盖。
• 平台端从保存的起始端口开始，在最多 100 个端口范围中探测可用候选；启动后直接请求该已知 loopback 端口的 /json/version，只有验证成功才把该端口写入运行时结果。端口探测与浏览器绑定之间存在竞争时，不自动杀死或重复启动浏览器。
• 启动前先合并 Chub launcher registry 与 Windows 外部 profile inspector 结果。目录被外部占用时，只读取该目录的 DevToolsActivePort，不扫描全系统 Chrome/Edge 进程或端口。
• 外部端点验证失败、端口文件过期、权限不足或浏览器类型不匹配时，保守报告外部/未知占用并拒绝启动；不得借此接管外部 PID。
• Gio 设置增加带 Label 和帮助文本的“远程调试起始端口”数字输入；空值在保存时归一化为 9666，有效值为 1024 至 65535。
• Gio 实例列表增加“调试端口”字段及 1dp 外层边框、圆角和表头分隔；端口值为实际关联端口、检测中或 —。行级启动结果沿现有异步 channel 回到 UI 线程，避免阻塞 frame。
• 托管运行、外部已关联、外部占用和启动失败使用不同文字状态；外部已关联只保留“重新检测”语义，不成为可关闭/重启的托管实例。

验收要点

• 启动 Chrome/Edge 时实际追加 loopback remote debugging 参数，默认从 9666 选择；首个端口占用时尝试后续端口，并在实例列表显示已验证的实际端口。
• 同一规范化 User Data Dir 的外部 Chrome/Edge 若存在有效 DevToolsActivePort，启动操作不创建新进程，列表显示“外部已关联”、PID、来源和端口。
• 外部浏览器未启用 CDP 或无法验证时，不创建新进程，列表显示外部/未知占用与可恢复说明。
• 端口输入可保存、恢复、校验和取消；空值恢复为 9666，非法端口在字段附近显示错误。
• 实例列表外框、表头和紧凑端口列在默认窗口宽度下不挤压启动/删除图标；端口为空显示 —。
• 外部关联没有关闭、重启、强制终止或全局按进程名操作；CDP WebSocket URL 不进入配置、日志、事件或 UI。
• go test ./...、go vet ./...、Windows build、真实 Chrome/Edge CDP/外部关联 smoke 和既有 Windows smoke 通过。

执行记录

• 状态：DONE
• 变更：LaunchSpec 新增受控 remote debugging port 并固定生成 loopback 参数；设置持久化并恢复起始端口（空值/旧配置默认 9666）；新增端口递增、DevToolsActivePort 解析和 /json/version 浏览器类型校验。GUI 启动链路会拒绝未验证的外部占用、关联可验证的外部实例、展示 PID/端口/来源，并将端口作为列表边框内的独立字段。真实 smoke 以已知端口校验 Chrome/Edge CDP，并在任意失败路径按 profile 清理测试进程。
• 验证：gofmt、go test ./...、go vet ./...、go build -o build/chub.exe ./cmd/chub、scripts/smoke-browser.ps1（真实 Chrome/Edge loopback CDP）和 scripts/smoke-windows.ps1 均通过。
• 阻塞：无。
• 残余风险：Chrome 默认用户目录可能忽略 remote debugging 开关；端口预探测存在不可消除的短暂竞争，最终以端点验证为准。外部浏览器未留下 DevToolsActivePort 时，Chub 不会猜测或扫描端口以避免把其他 profile 的 CDP 端点错误关联，只报告外部占用。