cdp_hub/docs/04-architecture.md

# 架构设计

```text
Gio UI / CLI
    ↓ DTO + commands
Application BrowserManager
    ↓ ports
Platform Windows
    ├─ executable discovery
    ├─ launcher
    ├─ process identity / query
    ├─ graceful close / force kill
    ├─ Job Object
    ├─ profile occupancy inspector
    ├─ loopback CDP endpoint inspector
    ├─ loopback CDP target reader (read-only `/json/list`)
    ├─ remote-debug port allocator
    ├─ instance status refresher
    ├─ portable config path resolver / legacy migrator
    └─ notification-area adapter (Windows Shell)
    ↓
Chrome / Edge processes
```

UI/CLI 不直接操作 `exec.Cmd`、Win32 handle 或数据库。Application 层维护实例状态和授权边界；Platform 层只提供系统能力。

## 实例身份

每个实例至少记录 `instance_id`、browser kind、executable、root PID、user data dir、profile directory、非敏感参数摘要、关联的 loopback CDP 端口、归属（托管或外部关联）、创建时间、状态和退出码。

进程身份校验至少比较 PID 存活、executable、命令行中的规范化 `--user-data-dir` 和注册记录。无法确认身份时只能报告 UNKNOWN，不允许关闭。

## 生命周期

`CREATED -> STARTING -> RUNNING -> STOPPING -> EXITED`；启动失败为 `FAILED`，无法确认的外部实例为 `UNKNOWN`。

- 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 或已校验进程树，不按名称全局终止。
- Restart：旧实例退出或完成超时处理后重新执行同一配置。
- App shutdown：取消监控，不默认终止用户浏览器。
- Refresh：以 UI 传入的保存实例快照为范围，在后台读取 Chub registry、对应 profile 占用证据与已知 loopback CDP 端点，返回状态 DTO。刷新不按浏览器进程名或端口范围枚举；结果以实例 ID 与快照版本关联，UI 丢弃已删除或已编辑行的过期结果。
- Edit：UI 只提交可持久化的实例配置 DTO；运行时 PID、关联端口、占用来源和状态由刷新/启动结果返回，不作为编辑表单保存字段。编辑时保留未公开的非敏感启动选项，活跃或外部关联实例的身份约束字段保持只读。
- Proxy：本地配置保存稳定 `proxy_id` 指向的代理库项（名称与无认证端点）；启动 adapter 在后台解析为当前 `LaunchSpec.ProxyServer` 快照。代理不能含 userinfo，删除被引用项会被拒绝；修改代理只影响后续启动，不影响已运行实例。
- GUI stop：主操作只对 Chub registry 中可验证的托管实例调用 `StopProfile(userDataDir, false)`，随后有限等待 registry 释放。外部关联、占用和未知实例永远不调用停止接口；超时或失败不自动强制关闭。
- 受管退出监控：仅为当前会话由 Chub 启动并获得进程句柄的实例建立一个 `Wait` 监控任务。退出事件携带实例 ID、启动代次和 PID，UI 仅在三者仍匹配且当前未处于 Chub 请求的停止中时，将运行时状态改为“已退出”并排队显示提示；过期事件、外部实例和应用退出后的监控取消均不得生成意外退出提示。
- CDP 页面目标查看：UI 仅将当前已保存实例快照交给后台 adapter；adapter 只接受“运行中”或“外部已关联”的有效实际端口，先复核对应 browser kind 的 loopback `/json/version`，再读取同一端口的 `/json/list`。结果 DTO 仅含 target ID、标题、类型和脱敏 URL；UI 以实例 ID、端口和请求代次丢弃过期结果。该链路不建立 WebSocket、不开启页面控制，也不提供物理窗口 ID。
- 通知区域：Windows platform adapter 在独立原生消息循环中管理一个图标、Tooltip 和原生菜单，向 `cmd/chub` 发送仅含“显示主窗口 / 刷新状态 / 退出应用”的 typed command。应用 coordinator 决定如何显示 Gio 窗口、发起既有刷新或执行退出清理；adapter 不持有浏览器进程句柄，不调用浏览器启动/停止接口。图标状态仅来自非敏感实例计数；Explorer 重启后重新注册，应用结束前删除图标。首版不拦截 Gio 的窗口关闭消息，也不隐藏主窗口。
- 配置定位与迁移：`config.OpenDefault()` 先用 `os.Executable()` 的目录解析目标 `config.json`，不依赖工作目录。目标文件已存在时直接使用它；目标不存在时仅尝试读取旧 `%APPDATA%\\chub\\config.json`，通过现有 decode/normalize 校验后以 Store 原子写入目标，并把旧文件保留为只读恢复备份。迁移失败不会写入目标、不会删除旧文件、不会回退到 AppData 继续运行；应用层只显示可恢复的启动诊断，不显示配置内容。CLI 与 GUI 共用该入口，避免出现不同配置来源。

Chrome 和 Edge 共用大部分 Chromium 参数，但 executable 默认路径、进程名称和安装方式不同，通过 `BrowserDefinition` 封装差异。CDP 端点只绑定 `127.0.0.1`；端口号和 `/json/version` 是诊断数据，WebSocket URL 不进入持久化、事件或普通 UI 文案。`/json/list` 仅用于只读页面目标信息；URL 在 DTO 边界移除 userinfo、query 和 fragment。

## 风险

Chromium 可能复用已有进程；浏览器是多进程架构；管理员权限进程可能无法查询；强制终止可能损坏 profile；CDP 端口开放到非 loopback 会形成控制风险，MVP 默认关闭。