@mearl/native-host

@mearl/native-host

Mearl 的 Native Messaging Host —— 桥接 Chrome 扩展与本地 socket 服务。

浏览器扩展通过 chrome.runtime.connectNative() 拉起本进程；进程对内通过 CDP（Chrome DevTools Protocol）与浏览器交互，对外通过 Unix Socket 暴露给 @mearl/client 等本地调用方，并可作为云端链路的本地落点。

安装与注册

注册 Native Messaging Host manifest（让浏览器能够拉起本进程）：

# 同时注册 Skills 与 MCP 两种集成模式（默认）
mearl-native-host --init

# 仅注册某一种模式
mearl-native-host --init --mode skills
mearl-native-host --init --mode mcp

# 指定自定义扩展 ID（开发版）
mearl-native-host --init --extension-id <your-extension-id>

Skills 与 MCP 两个 host 运行同一份二进制、共享同一个 Unix socket，因此可同时启用。

也可在代码中调用安装入口：

import { installNativeHost } from '@mearl/native-host';

await installNativeHost(); // 默认注册两种模式

运行时入口（被浏览器拉起、或手动启动）通过子路径导出：

import '@mearl/native-host/runtime';

CLI 选项

mearl-native-host [options]

  --init [--mode <skills|mcp|both>] [--extension-id <id>]   注册 host manifest
  --daemon                                                   独立 CDP daemon
  --cdp-port <port>                                          指定 CDP 端口
  --cdp-user-data-dir <dir>                                  指定 Chrome Profile
  --agentbay-session-id <id>                                 连接 AgentBay CDP Session
  --agentbay-idle-release-minutes <minutes>                  AgentBay 空闲回收时间（内部参数）
  --browser-id <id>                                          指定浏览器注册 ID
  --browser-name <name>                                      指定浏览器显示名称
  --version, -v                                             查看版本
  --help, -h                                               查看帮助

架构

Chrome Extension
  ↓ (Native Messaging)
@mearl/native-host  ← CDP →  Chrome
  ↓ (Unix Socket)
@mearl/client  /  @mearl/cloud-connector

browser_launch 会为每个托管 Chrome 启动一个带独立 CDP 配置的 native-host 子进程，使多个 headless/Profile/TDBank 账号实例可以同时被现有浏览器注册表寻址。设计细节见 托管浏览器与 TDBank 多账号设计。

AgentBay 会话创建时使用官方 LifecyclePolicy：默认 30 分钟没有 Mearl 指令时由本地宿主执行优雅关闭，120 分钟达到云端最大运行时长时由 AgentBay 强制释放。优雅关闭会先同步持久化 Browser Context，再删除 Session 和本地注册记录；执行中的 Mearl action 不计为空闲。正常任务仍应主动调用 browser_close，超时只用于异常退出兜底。

运维环境可覆盖默认值；两项均为正整数分钟，空闲时间至少为 3，最大运行时长不得小于空闲时间：

MEARL_AGENTBAY_IDLE_RELEASE_MINUTES=30
MEARL_AGENTBAY_MAX_RUNTIME_MINUTES=120

侧边栏 Agent Chat

扩展侧边栏通过 Native Messaging 调用 native-host，再按用户选择启动持久的 Codex app-server 或 Qoder ACP 进程。两种 Provider 都支持流式消息、思考与工具进度、中断和审批，并复用各自 CLI 已保存的本地登录态。

需要先安装并登录支持 app-server 的 Codex CLI。若事件中的模型错误提示需要更新版本，应先升级本机 Codex CLI。native-host 会依次从安装时的 Node 可执行文件目录、常见全局安装目录和 PATH 查找 codex；自定义路径可通过环境变量指定：

MEARL_CODEX_PATH=/absolute/path/to/codex

Qoder 使用官方 ACP 接口，需要先安装 Qoder CLI 并完成登录：

# macOS / Linux
curl -fsSL https://qoder.com/install | bash
qodercli
# 进入交互界面后输入 /login

# 可选：指定非标准安装位置
MEARL_QODER_PATH=/absolute/path/to/qodercli

侧边栏 Agent 不使用只读或工作区沙箱限制，文件、命令和网络操作由 Provider 的审批机制控制。用户选择的本地目录只作为对话的参考上下文和相对路径起点，不限制 Agent 可访问的范围；未选择时从用户主目录开始，Codex 可通过 MEARL_AGENT_CWD 覆盖默认起点。Agent 接入由统一 Provider 接口承载，后续可新增 Claude 等实现而无需修改扩展与 native-host 之间的 Chat 协议。只安装 ChatGPT 等桌面聊天客户端不能替代 Provider CLI；侧边栏会在 CLI 缺失时展示安装与登录指引。

构建

pnpm build      # esbuild 打包到 dist/（内联 browser-core / daemon-core）
pnpm typecheck  # 仅类型检查

License

ISC