@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
  --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 多账号设计。

侧边栏 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

侧边栏中未选择本地目录时，Codex 对话使用只读沙箱且不允许提权，Qoder 对话通过首条提示词约束为只读模式；选择后才使用该目录作为可写工作区。MEARL_AGENT_CWD 仅用于 Codex 只读对话的默认浏览目录，不会开启写权限；Qoder 未选目录时从用户主目录开始浏览。Agent 接入由统一 Provider 接口承载，后续可新增 Claude 等实现而无需修改扩展与 native-host 之间的 Chat 协议。只安装 ChatGPT 等桌面聊天客户端不能替代 Provider CLI；侧边栏会在 CLI 缺失时展示安装与登录指引。

构建

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

License

ISC