chore: establish chub go foundation

docs/api.md

@@ -0,0 +1,68 @@
+# API / 模块合约
+
+MVP 首先提供本地 Go application service 和 CLI；是否增加 loopback HTTP/WebSocket 在 T-203 决策。时间使用 RFC3339，路径使用规范化绝对路径。
+
+## 核心类型
+
+```go
+type BrowserKind string
+const (
+    BrowserChrome BrowserKind = "chrome"
+    BrowserEdge BrowserKind = "edge"
+)
+
+type LaunchSpec struct {
+    Kind BrowserKind
+    Executable string
+    UserDataDir string
+    ProfileDirectory string
+    TargetURL string
+    ProxyServer string
+    Headless bool
+    ExtraArgs []string
+}
+
+type InstanceView struct {
+    ID string
+    Kind BrowserKind
+    PID int
+    UserDataDir string
+    Status string
+    ExitCode *int
+}
+```
+
+## 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` 触发。
+
+## 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、完整代理认证信息或原始系统堆栈。