@bysking/browser-store

v0.1.2

Published

a month ago

浏览器多开管理 CLI：基于 Chrome/Edge 多开实例，独立 profile 与会话，独立 CDP 调试端口，每个实例可暴露 MCP Server 给 AI 客户端，带 umijs 管理台

0High
0Medium
0Low

bysking

browser chrome edge multiprofile cdp mcp cli

browser-store

核心能力

| 能力 | 说明 | |---|---| | 多开实例 | 每个实例独立 --user-data-dir profile 目录，会话 / cookies / 登录态互不影响 | | 独立 CDP 端口 | 每实例自动分配独立 --remote-debugging-port（默认 9222 起，冲突自动 +1 重分配） | | MCP Server | 每实例可暴露为 MCP server，AI 客户端直接操控该浏览器（导航/截图/点击/填表/执行 JS 等 16 个工具） | | 生命周期 | 新增 / 编辑 / 删除 / 启动 / 关闭 / 重置（清 profile 还原），状态机完整管理 | | 管理台 | umijs 前端嵌入 CLI，bs serve 单端口出全站 | | 发布 | esbuild 单文件 bundle，npx 即装即用，无需安装浏览器驱动 |

安装

npm i -g @bysking/browser-store   # 全局安装
# 或
npx -y @bysking/browser-store     # 免安装直接使用

要求：Node.js >= 20.10.0

从源码构建：

git clone https://github.com/bysking/browser-store.git
cd browser-store
pnpm install
pnpm build                       # 产出 dist/cli.cjs + dist/public
node dist/cli.cjs --version      # 验证

快速开始

# 1. 探测本机已安装浏览器
bs discover

# 2. 新增实例
bs add work --engine chrome
bs add edge1 --engine edge --headless --urls https://example.com,https://github.com

# 3. 启动 / 停止 / 重启 / 重置
bs start work
bs stop work
bs restart work
bs reset work --yes          # 清空 profile 还原（自定义目录需 --force）

# 4. 即开即用：实例不存在自动创建，命令退出后浏览器保持运行
bs open work https://example.com

# 5. 查看状态 / 日志
bs ls
bs info work
bs logs work --follow

# 6. 启动常驻服务（API + 管理台 + HTTP MCP）
bs serve
# 浏览器打开 http://localhost:3210 进入管理台

# 7. 让 AI 操控浏览器（MCP）
bs mcp-register work          # 拿到 Claude Desktop 配置片段

帮助

$ bs --help

用法: bs [options] [command]

浏览器多开管理 CLI — 独立 profile / 独立 CDP 端口 / 每实例 MCP Server

选项:
  -v, --version              输出版本号
  -h, --help                 display help for command

命令:
  serve [options]            启动常驻服务（HTTP API + umijs 管理台 + 实例生命周期 + HTTP MCP）
  open [options] <name> [url] 即开即用：打开（必要时创建）实例并导航到 URL，命令退出后浏览器保持运行
  add [options] <name>       新增浏览器实例
  ls|list [options]          列出所有实例及状态
  start <name>               启动实例
  stop <name>                停止实例
  restart <name>             重启实例
  reset [options] <name>     重置实例：停止 + 清空 profile 还原（默认需确认）
  prune [options] [name]     清理实例的可再生缓存/指标目录（需先停止，不影响会话数据）
  rename <name> <newName>    重命名实例
  rm|remove [options] <name> 删除实例（需先停止）。默认保留 profile，--purge 连带删除
  mcp <name>                 为实例启动 stdio MCP server（供 Claude Desktop 等 AI 客户端接入）
  mcp-register <name>        打印/写入该实例的 Claude Desktop mcpServers 配置片段
  discover                   探测本机已安装浏览器
  doctor                     诊断：node 版本、浏览器、端口、CDP 可达性
  logs [options] <name>      查看实例日志
  info <name>                查看实例完整配置 + 状态 + CDP/MCP 地址

命令参考

| 命令 | 说明 | |---|---| | bs serve [--port] [--host] [--stop-all-on-exit] | 常驻服务：HTTP API + 管理台 + 生命周期 + HTTP MCP | | bs open <name> [url] [--engine] | 即开即用：打开（必要时创建）实例并导航，命令退出浏览器保持运行 | | bs add <name> [--engine] [--profile-dir] [--debug-port] [--mcp-port] [--headless] [--urls] [--mcp-transport] | 新增实例 | | bs ls / list [--json] | 列出实例及状态 | | bs start / stop / restart <name> | 启停 / 重启 | | bs reset <name> [--yes] [--no-start] | 重置：停止 + 清空 profile 还原 | | bs rename <name> <newName> | 重命名 | | bs rm <name> [--yes] [--purge] | 删除实例（交互选择是否连带删 profile，--purge 连带删） | | bs mcp <name> | 为该实例启动 stdio MCP server | | bs mcp-register <name> | 打印 Claude Desktop mcpServers 配置片段 | | bs discover | 探测本机浏览器 | | bs doctor | 诊断：node / 浏览器 / 端口 / CDP 可达性 | | bs logs <name> [--follow] [--tail N] | 查看 / 跟随日志 | | bs info <name> | 完整配置 + 状态 + CDP/MCP 地址 |

MCP 接入 Claude Desktop

对任一实例执行 bs mcp-register <name>，把输出的片段加入 Claude Desktop 配置，即可让 AI 直接操控该实例（详见 docs/claude-desktop-setup.md）。

HTTP 模式：bs serve 后每个运行中的实例暴露 http://localhost:<port>/mcp/<instanceId>（Streamable HTTP），任何标准 MCP 客户端可连接。

数据存储

全部 JSON 存储于本地（可用 BS_HOME 覆盖根目录）：

~/.browser-store/
├── instances.json   # 实例配置（用户可编辑）
├── state.json       # 运行时状态（daemon 独占写）
├── daemon.json      # daemon 发现信息（CLI 路由用）
├── profiles/<id>/   # 受管 profile 目录
└── logs/<id>.log    # 实例日志

安全说明

CDP 调试端点仅监听 127.0.0.1，启动参数含 --remote-allow-origins=*（Chrome 111+ CDP WebSocket 必需），仅限本地可信环境
reset 默认只清受管目录的 profile；自定义目录需 --force 并确认，防误删用户数据
bs serve 退出默认不杀已启动的浏览器（--stop-all-on-exit 才全停），实例可被下次启动的 daemon 收养

架构

browser-store/
├── bin/bs.ts           # CLI 入口（esbuild bundle）
├── src/
│   ├── cli.ts          # commander 命令定义
│   ├── commands.ts     # 命令实现
│   ├── serve.ts        # 常驻服务 + daemon.json + 孤儿收养
│   ├── config/         # instances.json / state.json / 路径
│   ├── engines/        # BrowserEngine 可插拔（chrome / edge）
│   ├── instance/       # 端口分配 / spawn / 状态机 / 进程管理
│   ├── cdp/session.ts  # chrome-remote-interface 封装
│   ├── mcp/            # MCP 工具 + stdio + Streamable HTTP
│   └── api/            # REST + SSE 事件流
├── web/                # umijs 管理台（构建产物嵌入 dist/public）
└── docs/

详细规划见 docs/architecture-plan.md，功能与使用技巧见 docs/help-center.md。

开发

pnpm install
pnpm exec tsx bin/bs.ts --help     # dev 运行
pnpm typecheck                     # 类型检查
pnpm lint                          # 代码规范检查
pnpm build                         # esbuild bundle + web 构建 + 静态拷贝
node dist/cli.cjs --version        # 产物运行
pnpm test                          # 单元测试

贡献

欢迎参与贡献！请阅读 CONTRIBUTING.md 了解开发环境、提交规范与 PR 流程。提交前请确保 pnpm typecheck、pnpm lint、pnpm test 全部通过。

License

本项目采用 MIT + 商业授权 双许可模式：

个人 / 开源 / 学术用途：遵循 MIT 许可，完全免费
商业用途：需取得作者书面授权，详见 LICENSE

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme