44 lines
3.6 KiB
Markdown
44 lines
3.6 KiB
Markdown
|
---
|
||
|
|
id: T-302
|
||
|
|
title: 本地 CDP 启动、外部关联与实例端口展示
|
||
|
|
phase: 3
|
||
|
|
deps: [T-102, T-301]
|
||
|
|
status: DOING
|
||
|
|
created: 2026-07-25
|
||
|
|
owner: 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 个端口范围中探测可用候选；启动后等待 `DevToolsActivePort` 并请求 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 通过。
|
||
|
|
|
||
|
|
## 执行记录
|
||
|
|
|
||
|
|
- 状态：DOING
|
||
|
|
- 变更：已建立需求、架构、API、交互、原型和任务契约；待实现。
|
||
|
|
- 验证：文档待实现验证。
|
||
|
|
- 阻塞：无。
|
||
|
|
- 残余风险：Chrome 默认用户目录可能忽略 remote debugging 开关；端口预探测存在不可消除的短暂竞争，最终以端点验证为准。
|