cdp_hub/docs/api.md

API / 模块合约

MVP 首先提供本地 Go application service 和 CLI；是否增加 loopback HTTP/WebSocket 在 T-203 决策。时间使用 RFC3339，路径使用规范化绝对路径。

核心类型

代码权威类型位于 internal/domain/browser.go：BrowserKind、LaunchSpec、InstanceStatus、InstanceView、BrowserEvent 和稳定错误码。LaunchSpec.Normalize() 负责 browser kind、绝对 user data dir、受控的 loopback remote debugging port，以及非空时的 http/https URL 校验；空 URL 表示打开浏览器默认页。

LaunchSpec 使用已分配的 RemoteDebugPort；端口分配不属于 UI，也不允许由 ExtraArgs 覆盖。InstanceView 返回实际关联端口、PID、占用来源和归属。外部关联只公开经 DevToolsActivePort 与 /json/version 验证的端口，不公开 CDP WebSocket URL。

Application service

type BrowserManager interface {
    Start(ctx context.Context, spec LaunchSpec) (InstanceView, error)
    List(ctx context.Context) ([]InstanceView, error)
    Get(ctx context.Context, id string) (InstanceView, error)
    Stop(ctx context.Context, id string, force bool) error
    Restart(ctx context.Context, id string) (InstanceView, error)
}

Stop(force=false) 只执行优雅关闭；强制关闭必须由明确用户动作或 CLI --force 触发。

平台实现通过实例级 StopProfile(userDataDir, force) 执行关闭；force 只对已注册并经过身份绑定的实例生效。

参数数组由 internal/platform/browser.BuildArgs 生成；Chrome/Edge executable 由同包 Discoverer.Resolve 解析。二者都不接收 shell 命令行字符串。CDP 端点检测和端口分配均通过 platform port 执行，UI 只消费 DTO 结果。

CLI 当前合约

chub start --browser chrome --user-data-dir <dir> [--profile-directory <name>] [--url <url>]
chub list
chub stop <instance-id> [--force]
chub restart <instance-id>
chub events

退出码：0 成功，2 参数错误，3 profile 占用，4 实例不存在，5 身份校验失败，6 系统权限/进程错误。

当前 list 和 events 已输出 JSON；events 输出本地配置快照 JSON，后续 loopback transport 接入后升级为 JSON Lines 持续流。start/stop/restart 已保留稳定命令和错误码，等待 BrowserManager adapter 接入。

事件

事件	触发	负载
browser.started	新实例完成启动	InstanceView
browser.status.changed	状态变化	instance_id、status、pid、remote_debug_port、ownership、error_code
browser.exited	进程退出	instance_id、exit_code

事件禁止携带密码、Cookie、Token、完整代理认证信息或原始系统堆栈。

应用内 application.EventBus 使用带缓冲的订阅通道，发布不阻塞进程监控；UI 通过订阅刷新状态，取消订阅会关闭对应通道。