核心概念

环境与实例

环境（Environment）= 一份配置：hosts 配置源、keepAlive 开关、启动参数、登录态快照、扩展注册表。环境本身不运行浏览器。

实例（Instance）= 环境的一次隔离运行：

• 独立 user-data-dir（Profile、Cookie、localStorage 全隔离）；
• 独立 CDP 端口（本机 9222 起动态分配，实例重启可能变化——每次现查，不要缓存）；
• 可选名字（创建时传入，同环境内唯一；多任务并行时按名锚定，见下文「实例命名」）；
• 独立 Chrome 进程。实例数据随 profile 目录保留，直到显式删除实例。

同一环境可以同时开多个实例，互不串扰；停止实例释放进程与端口，数据保留。

实例命名

多任务并行时按名锚定实例，比记 ins_ id 省心：

• 创建：instance create <envId> --name <任务名>（REST body { "name": "checkout-e2e" }）；名字 1-64 字符、非纯空白，同环境内唯一（重名 → 409 INSTANCE_NAME_CONFLICT）；不命名完全合法；
• 按名引用：CLI 的实例命令吃 id 或 name（name 全局唯一命中时自动解析），如 instance stop qa任务A；
• 同名跨环境消歧：按名引用命中多个环境的同名实例 → exit 2 列出候选，改用 id。

登录态快照（Login Profile）

针对「每个实例都要重新登录」的痛点：

1. 环境开启登录态后，母本登录浏览器中完成登录；
2. 捕获快照（登录态落盘）；
3. 之后在该环境创建的每个实例自动克隆该快照，启动即免登录；
4. 快照可刷新（重新捕获）与重置。

边界：session cookie 登录态重启即失效（Chrome 标准语义，session cookie 不落盘）。此类系统的免登录路径 = 每次在实例里登录（复用 running 实例可避免重复登录）。

hosts 注入

实例启动时从环境的 hosts 配置源（http(s):// URL）现拉最新配置，经 Chrome 的 --host-resolver-rules 进程级注入：

• 只影响该实例进程，不改系统 hosts；
• 配置源更新后，下次启动实例自动生效；
• 实例停止即失效，无残留。

keepAlive

环境级开关，开启后该环境的实例异常退出时自动重启：

• 判死有防线：探活失败 ≠ 死亡，CDP 端口二次确认后才处置（防误杀）；
• 熔断：60 秒窗口内连续崩溃 3 次 → 停止自动重启并标记 error，防重启风暴；
• 用户主动 stop 的实例不会被拉起。

扩展（Extensions）

扩展分两类：

• 系统扩展：应用内置，随启动自动同步，锁定不可禁用/移除（EXTENSION_SYSTEM_LOCKED）。当前内置：
  • Environment Label（环境标签角标）：document_start 即在每个实例窗口叠加环境名角标（不等页面加载完成，慢页面/白屏期间即可区分环境），位置/颜色在 Settings 页配置；错误页/崩溃页/about:blank 不运行 content script，无标签；
  • Net Rules（网络规则）：按环境注入 block/redirect/headers 网络规则（浏览器层 DNR 生效，worker 休眠不影响拦截）；配置形状与作用域见 AGENT-API.md Extensions 节（GUI Extensions 页「配置」/ CLI extension config / MCP set_extension_config 均可写入，per-env 覆盖全局默认）；
  • Page Diagnostics（页面诊断）：在每个 http(s) 页面采集 JS 错误与失败资源（各环形 100 条）+ LCP/FCP，挂载在页面全局供查询端点透传（GUI 无独立入口；CLI instance diagnostics / REST GET /instances/:id/diagnostics / MCP get_diagnostics）；
  • 常驻诊断（M6，非扩展）：实例启动后 chrome-host 维持一条只订阅的 CDP 连接（console 500 条 / 请求 1000 条环形缓冲，进程内态重启即清），提供 console/network/screenshot/HAR 查询（GET /instances/:id/console|network|screenshot|har，CLI/MCP 同名能力）；响应按「证据边界契约」（AGENT-API.md）自带 meta：dropped（环溢出累计丢弃）/capacity/since（watcher 挂载时刻，更早数据从未采集）/live，network 与 HAR 另声明 scope:"completed"（进行中的请求不可见），HAR 顶层 _meta 同时标注 -1 占位语义；网络条目另携带 bodyState/bodyReason（available/partial/evicted/unavailable 多态）：文本类 mime 的响应体自动拉取（单条 ≤256KiB、环级 8MiB 分层驱逐）、落环前脱敏（敏感 query/字段值 → [redacted]），可经 GET /instances/:id/network/:requestId/body 分页读（UTF-16 单位计量）；
• 用户扩展：任意本地扩展目录，GUI Extensions 页选目录注册，或 CLI extension add；可启停、可删除。

实例启动时自动以 --load-extension 注入当前启用的扩展；全部不可用时不阻断启动。

诚实证据（证据边界）

常驻诊断的 console / network / HAR 查询遵守同一条设计哲学：「没采到」≠「没发生」——宁可明说不完整，不静默装作完整。每份响应的 meta 自带证据边界：

meta 字段	含义	防的误读
dropped	环形缓冲溢出累计丢弃条数	dropped ≠ 0 → 早于窗口的事件已丢失，别当「没有报错」
since	采集窗口起点（watcher 挂载时刻）	更早的数据从未被采集，不是「没查到」
live	采集是否存活	false = 已停止采集，数据是残照
scope: "completed"	只见已完成的请求	进行中的请求不可见，等完成再查

响应体另有 bodyState（available / partial / evicted / unavailable + reason）逐条披露 body 可用性（机制见上文「扩展 · 常驻诊断」）。排障读历史时先看 meta：证据不完整时明说「证据不完整」，而不是把「没采到」误报成「没问题」。缓冲是进程内态，实例重启即清；HAR 未采集字段以 -1/空集占位（占位语义在 HAR 顶层 _meta 声明）。

内核（Chrome for Testing）

应用自管浏览器内核：首次启动自动下载 pinned 版 Chrome for Testing（双镜像），状态与版本见 Settings 页；随应用升级切换版本，不用系统 Chrome。

四入口共享服务层

GUI、Agent API（REST）、MCP、CLI 四个入口调用同一套服务层，行为与错误码完全一致：

入口	地址	适用
GUI	桌面应用	人工管理
REST	http://127.0.0.1:17890/api/v1	自动化脚本 / 任意语言客户端
MCP	http://127.0.0.1:17890/mcp	AI Agent（Claude Code 等）
CLI	chrome-host 命令	终端 / CI / Agent 编排

所有入口仅绑定本机回环地址（127.0.0.1），API 不会暴露到网络。