2026-07-22 14:51:11 +08:00
# API / 模块合约
MVP 首先提供本地 Go application service 和 CLI；是否增加 loopback HTTP/WebSocket 在 T-203 决策。时间使用 RFC3339，路径使用规范化绝对路径。
## 核心类型
2026-07-22 14:53:39 +08:00
代码权威类型位于 `internal/domain/browser.go` ： `BrowserKind` 、`LaunchSpec` 、`InstanceStatus` 、`InstanceView` 、`BrowserEvent` 和稳定错误码。`LaunchSpec.Normalize()` 负责当前已确定的 browser kind、绝对 user data dir 和 http/https URL 校验。
2026-07-22 14:51:11 +08:00
## Application service
```go
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` 触发。
2026-07-22 14:55:35 +08:00
参数数组由 `internal/platform/browser.BuildArgs` 生成；Chrome/Edge executable 由同包 `Discoverer.Resolve` 解析。二者都不接收 shell 命令行字符串。
2026-07-22 14:51:11 +08:00
## CLI 目标形状
```text
chub start --browser chrome --user-data-dir <dir> [--profile-directory <name>] [--url <url>]
chub list
chub stop <instance-id> [--force]
chub restart <instance-id>
```
退出码：0 成功，2 参数错误，3 profile 占用，4 实例不存在，5 身份校验失败，6 系统权限/进程错误。
## 事件
| 事件 | 触发 | 负载 |
| --- | --- | --- |
| `browser.started` | 新实例完成启动 | InstanceView |
| `browser.status.changed` | 状态变化 | instance_id、status、pid、error_code |
| `browser.exited` | 进程退出 | instance_id、exit_code |
事件禁止携带密码、Cookie、Token、完整代理认证信息或原始系统堆栈。
