cdp_hub/docs/04-architecture.md

架构设计

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
    └─ remote-debug port allocator
    ↓
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。未占用时从配置的起始端口选择可用 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：取消监控，不默认终止用户浏览器。

Chrome 和 Edge 共用大部分 Chromium 参数，但 executable 默认路径、进程名称和安装方式不同，通过 BrowserDefinition 封装差异。CDP 端点只绑定 127.0.0.1；端口号和 /json/version 是诊断数据，WebSocket URL 不进入持久化、事件或普通 UI 文案。

风险

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