# browser-agent-plugin

**Repository Path**: light-year/browser-agent-plugin

## Basic Information

- **Project Name**: browser-agent-plugin
- **Description**: 浏览器 agent 插件：Chrome 扩展（对话 UI + 浏览器工具执行端）+ 本地 Node 服务（agent 循环 + 能力包加载）。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# browser-agent-plugin

浏览器 agent 插件：Chrome 扩展（对话 UI + 浏览器工具执行端）+ 本地 Node 服务（agent 循环 + 能力包加载）。

## 目录结构

```
browser-agent-plugin/
├── docs/                 # 需求文档、协议设计
├── shared/               # 协议类型定义（@bap/shared）
├── server/               # 本地 Node Agent 服务（WS + agent 循环）
└── extension/            # Chrome MV3 扩展（Sidepanel UI）
```

## 开发

```bash
npm install

# 终端 1：启动本地服务
#   BAP_PORT          WS 端口（默认 8765）
#   BAP_TOKEN         配对 token（默认自动生成到 ~/.browser-agent-plugin/token）
#   BAP_MODEL_PROVIDER  anthropic | openai（不设则进入演示模式）
#   BAP_MODEL         模型名（默认 gpt-4o-mini / claude-sonnet-4-20250514）
#   BAP_SKILLS_DIR    技能目录（逗号分隔，追加到默认路径之后）：支持独立技能目录 / skills 根目录 / Claude Code 插件目录 / 插件安装根目录
#                     默认加载 ~/.claude/plugins（插件）与 ~/.claude/skills（技能）
#   BAP_KB_DIR        知识库目录（逗号分隔）：md/txt 文档，agent 经 kb_search 检索
#   BAP_DISABLE_PROMPT_CACHE  设为 1 关闭 Anthropic 提示缓存（第三方代理不支持 cache_control 时使用）
#   BAP_MAX_STEPS     单轮工具调用步数上限（默认 100）
npm run dev:server

# 终端 2：构建扩展（watch 模式）
npm run dev:extension
```

Chrome 加载：`chrome://extensions` → 开发者模式 → 加载已解压的扩展程序 → 选择 `extension/dist`。

> 权限说明：为支持 agent 读取/操作任意页面，扩展申请了 `tabs`、`scripting`、`debugger`（真实鼠标模拟，CDP）与 `<all_urls>` host permission（安装时 Chrome 会给出警告）。骨架阶段简化为侧边栏直接执行工具；后续将迁移到 background 并细化按站点授权。

点击扩展图标打开侧边栏，填入服务端 token（服务启动日志打印，或 `~/.browser-agent-plugin/token`），连接后即可对话。骨架版演示流程：流式回显 → 权限确认 → 浏览器工具调用 → 结束。

## 全局脚手架（npm 包 `bap-agent` / `bap` 命令）

服务与 Web UI 封装为可发布 npm 包（`packages/bap`），发布产物为单文件 CLI + 内置 Web UI 静态资源：

```bash
# 维护者：构建并发布（发布的是 packages/bap，即 npm 包 bap-agent，不是仓库根包）
npm run build:cli      # 1) 构建 Web UI（extension/dist-web）2) esbuild 打包 server → packages/bap/dist
npm run publish:cli    # 等价于 npm run build:cli && cd packages/bap && npm publish

# 用户：全局安装
npm install -g bap-agent
```

启动后控制台会打印 **Web UI 地址**，浏览器打开即是扩展同款对话界面：

```bash
$ bap
[bap] v0.1.0 启动中...
[server] listening on ws://127.0.0.1:8765/ws
[server] Web UI: http://127.0.0.1:8765/
[server] token: xxxx（Web UI 同源自动配对，无需手填）
```

三种使用形态：

1. **Web UI**：浏览器打开控制台打印的地址即可对话（配置模型供应商、技能、知识库均在设置页）；
2. **Chrome 扩展**：扩展侧边栏填入 token 连接 `ws://127.0.0.1:8765/ws`，提供浏览器工具执行能力（Web UI 无浏览器工具，agent 需要操作页面时会提示改用扩展）；
3. **两者可同时连接**，会话/配置由本地服务统一管理。

常用选项：`bap -p 9000`（端口）、`bap --token xxx`（固定 token）、`bap --kb-dir ~/docs -d ~/myproject`、`bap -h`（全部）。

本地开发态仍走 tsx：`npm run dev:server` / `npm run bap`；调试 Web UI 托管时用 `BAP_WEB_DIR=$PWD/extension/dist-web npm run dev:server`。

## 开源协议

[MIT](./LICENSE) © 光年以外

## 设计文档

- 《docs/需求.md》— 产品需求与能力包体系
- 《docs/协议设计.md》— 扩展 ↔ 服务 WS 协议（JSON-RPC 2.0 风格）