unmodeled-tyler/vessel-browser

Linux 上用于持久化 Web Agent 的开源浏览器 Runtime。 Vessel 为外部 Agent 框架提供了一个具有持久状态、MCP 控制和可视化监管 UI 的真实浏览器。它专为长时间运行的工作流而构建，在这些工作流中，Agent 负责驱动，而人类负责审计、干预和在需要时重新定向。 - **为 Agent 框架构建**，例如 Hermes Agent、OpenClaw 和其他 MCP 客户端 - **保持浏览器状态活跃**，支持命名会话、书签、检查点和结构化页面可见性 - **让人类参与循环**，提供审批、运行时控件和可视化浏览器，而不是无头黑盒 *Vessel 正处于活跃开发中，目前不提供任何安全保证。请谨慎使用和部署。* https://github.com/user-attachments/assets/0a72b48a-873a-4eb0-b8f2-23e34d8472c4 ## 快速开始 ### 目前最快的安装方式 从 GitHub Releases 下载 Linux AppImage： 1. 下载最新的 `Vessel--x64.AppImage` 2. 标记为可执行：`chmod +x Vessel-*.AppImage` 3. 启动它：`./Vessel-*.AppImage` 4. 打开设置 (`Ctrl+,`) 并确认那里显示的 MCP 端点 ### 通过 npm 安装 ``` npm install -g @quanta-intellect/vessel-browser vessel-browser ``` 或者直接运行而无需安装： ``` npx @quanta-intellect/vessel-browser ``` ### 源码安装 ``` curl -fsSL https://raw.githubusercontent.com/unmodeled-tyler/quanta-vessel-browser/main/scripts/install.sh | bash ``` ### 从源码开发 ``` npm install npm run dev ``` 如果你在开发中需要额外的本地 AI 追踪，可以创建一个可选的 `src/main/telemetry/trace-logger.local.cjs` 文件。Vessel 只会在本地开发构建中加载它，打包的生产构建会忽略它。 ### 为什么选择 Vessel？ 大多数浏览器自动化技术栈要么是无头的，要么是无状态的，或者围绕人类作为主要操作者设计。Vessel 围绕相反的模型构建：浏览器是 Agent 的操作界面，人类通过具有明确监管控件的可视化界面参与循环。 Vessel 专为需要真实浏览器、持久状态和可视化界面的持久化 Web Agent 而构建。Agent 是主要操作者。人类在实时的浏览器 UI 中跟随，审计 Agent 正在做什么，并在需要时进行引导。 今天，Vessel 提供了支持该模型所需的浏览器外壳、页面可见性和监管界面。长期目标不是“一个带有 AI 功能的浏览器”，而是一个为自主 Agent 提供浏览器 Runtime，并为人类提供清晰监管体验的平台。 ## 功能特性 - **Agent 优先的浏览器模型** — Vessel 围绕 Agent 驱动浏览器而设计，同时人类可以观察、干预和重定向 - **可视化的浏览器 UI** — 页面像普通浏览器一样渲染，因此 Agent 活动保持清晰可读，而不是消失在无头运行中 - **命令栏** (`Ctrl+L`) — 用于框架驱动工作流和未来运行时命令的辅助操作界面 - **监管侧边栏** (`Ctrl+Shift+L`) — 跨五个标签页的实时监管：监管、书签、检查点、聊天和自动化 - **聊天助手** — 侧边栏聊天标签页中内置的对话式 AI；支持 Anthropic、OpenAI、Ollama、Mistral、xAI、Google Gemini、OpenRouter 和任何 OpenAI 兼容端点；自动读取当前页面；拥有与外部 Agent 相同的浏览器工具访问权限；多轮会话历史；在设置中配置提供商、模型和 API 密钥 - **自动化套件** (高级版) — 侧边栏自动化标签页中的参数化工作流模板；填写简短表单，内置 Agent 自主执行工作流；捆绑套件包括 Research & Collect（带书签保存的多源研究）和 Price Scout（跨零售商比价）；为未来的套件市场而设计 - **开发者工具面板** (`F12`) — 在窗口底部的可调整大小面板中检查控制台输出、网络请求和 MCP/Agent 活动；按类别和日期范围将日志导出为 JSON - **Agent 书签** — 将页面保存到文件夹，附加单行文件夹摘要，并通过 MCP 搜索书签，而不是转储整个库 - **命名会话持久化** — 以可重用的名称保存 cookies、localStorage 和当前标签页布局，然后在重启后重新加载 - **页面高亮** — Agent 可以使用带标签的彩色标记在任何页面上视觉高亮文本或元素，这些标记在导航过程中持续存在；高亮计数和导航控件显示在侧边栏中；可通过工具调用显式清除 - **Agent 转录停靠栏** — 锚定在浏览器边框上的浮动转录覆盖层；可在设置中配置显示模式（关闭、摘要、完整）；显示实时的 Agent 思考和状态更新，而不占用侧边栏空间 - **工作流跟踪** — Agent 可以在运行时使用 `flow_start` 声明命名的多步骤工作流；通过 `flow_advance` 逐步跟踪进度，并在整个执行过程中在侧边栏中可见 - **结构化页面可见性上下文** — 提取功能可以报告视口内元素、被遮挡的控件、活动覆盖层和休眠的同意/模态 UI - **弹窗恢复工具** — Agent 可以显式关闭常见的弹窗、通讯订阅关口和同意墙，而不是暴力执行通用点击 - **单标签页广告拦截控制** — 标签页默认开启广告拦截，但 Agent 可以在页面行为异常时选择性地禁用和重新启用拦截 - **域名策略** — 在设置中全局配置域名白名单或黑名单；Agent 无法导航到被阻止的域名 - **Agent 凭证保管库** (高级版) — 用于 Agent 驱动登录的加密凭证存储；凭证通过“盲填”模式直接填入登录表单，从不发送给 AI 提供商；每次使用前都有用户同意对话框；支持 TOTP 2FA；域名范围访问；仅追加审计日志 - **截图与视觉分析** (高级版) — 截取整页截图并直接将图像传递给 AI 进行视觉布局分析；在文本提取失败的重型页面或 Canvas 渲染页面上非常有用 - **Obsidian 记忆钩子** (高级版) — 用于 Agent 编写的 Markdown 笔记、页面捕获和研究痕迹的可选库路径 - **运行时健康检查** — MCP 端口冲突、不可读设置和用户数据写入失败的启动警告 - **阅读模式** — 将文章内容提取为干净、无干扰的视图；可从地址栏开启和关闭 - **专注模式** (`Ctrl+Shift+F`) — 隐藏所有浏览器界面，内容填满屏幕 - **可调整大小的面板** — 拖动侧边栏边缘调整大小；宽度跨会话保持 - **极简深色主题** — 温暖的深灰色、克制的强调色，没有纯黑/纯白 ## 产品定位 大多数浏览器将自动化视为次要功能，并假设人类是主要行为者。Vessel 则相反：它是为 Agent 服务的浏览器，具有让人类参与循环的可视化界面。 这意味着产品应该优化于： - 跨任务和会话的持久浏览器状态 - 对 Agent 当前行为的清晰可见性 - 轻量级的人工干预，而不是持续的手动驱动 - 能够服务于长时间运行的 Agent 系统的浏览器 Runtime，例如 Hermes Agent 或 OpenClaw 风格的框架 ## 技术栈 | 层级 | 技术 | |-------|-----------| | 引擎 | Chromium (Electron 40) | | UI 框架 | SolidJS | | 语言 | TypeScript | | 构建 | electron-vite + Vite | | AI 控制 | 外部 Agent 框架 (Hermes Agent, OpenClaw, MCP 客户端) + 内置聊天 (Anthropic, OpenAI, Ollama, 和任何 OAI 兼容端点) | | 内容提取 | @mozilla/readability | ## 架构 ``` Main Process Renderer (SolidJS) ├── TabManager (WebContentsView[]) ├── TabBar, AddressBar ├── AgentRuntime (session + supervision) ├── CommandBar (secondary surface) ├── MCP server for external agents ├── AI Sidebar (Supervisor/Bookmarks/Checkpoints/Chat/Automate) ├── AI providers (Anthropic + OAI-compat) ├── DevTools Panel (Console/Network/Activity) ├── Supervision, bookmarks, checkpoints ├── Agent Transcript Dock └── IPC Handlers ◄──contextBridge──► ──► └── Signal stores (tabs, ai, ui) └── IPC Handlers ◄──contextBridge──► Preload API ``` 每个浏览器标签页都是一个由主进程管理的独立 `WebContentsView`。浏览器界面 (SolidJS) 运行在分层在其上的独立视图中。渲染进程和主进程之间的所有通信都通过 `contextBridge` 经由类型化 IPC 通道进行。 侧边栏自动化标签页完全在渲染器中渲染套件表单，并通过与聊天标签页使用的相同 `query()` 路径将渲染后的提示传递给内置 Agent —— 不需要额外的 IPC 接口。 ## 入门指南 安装程序会： - 将 Vessel 克隆或更新到 `~/.local/share/vessel-browser` - 安装依赖并构建应用 - 在 `~/.local/bin` 中创建 `vessel-browser` 启动器 - 在 `~/.local/bin` 中创建 `vessel-browser-launch` 辅助命令 - 在 `~/.local/bin` 中创建 `vessel-browser-update` 辅助命令 - 在 `~/.local/bin` 中创建 `vessel-browser-status` 辅助命令 - 为 Linux 应用启动器创建桌面入口 - 写入 `~/.config/vessel/vessel-settings.json`，MCP 端口为 `3100` - 写入 `~/.config/vessel/mcp-http-snippet.json` - 打印确切的 HTTP MCP 片段以粘贴到你的框架配置中 打包的 AppImage 方式： - 不需要本地 Node/Electron 工具链 - 使用打包的 Vessel 应用图标和元数据 - 是早期采用者只想运行 Vessel 的推荐方式 安装后： ``` vessel-browser ``` ``` # 安装依赖 npm install # 如果 Electron 下载失败，请使用镜像： ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install # 开发（使用 HMR） npm run dev # Production 构建 npm run build # 对 MVP release 路径进行冒烟测试 npm run smoke:test # 打包未解压的 Linux 应用 npm run dist:dir # 打包 Linux AppImage npm run dist ``` 注意： - `npm run dev` 仍然启动 stock Electron 二进制文件，因此 Linux 可能会在开发中继续显示默认的 Electron 齿轮图标 - 使用 `npm run dist` / `npm run dist:dir` 创建的打包构建使用 Vessel 应用图标 - 跟踪的冒烟测试运行类型检查、构建和 Electron 导航回归测试 - 对于无头 CI，在 `xvfb-run -a npm run smoke:test` 下运行冒烟测试 ### 为 Hermes Agent 或 OpenClaw 设置 Vessel Vessel 旨在充当外部 Agent 框架驱动的浏览器 Runtime。 1. 启动 Vessel 2. 打开设置 (`Ctrl+,`) 以确认 MCP 状态、复制端点或更改 MCP 端口 3. 可选：设置 Obsidian 库路径或会话首选项 4. 启动 Hermes Agent 或 OpenClaw 并配置它连接到 Vessel 的 MCP 端点 `http://127.0.0.1:/mcp` 5. 使用 Vessel 侧边栏中的监管面板在框架运行时暂停 Agent、更改审批模式、审查待处理审批、创建检查点或恢复浏览器会话 6. 使用书签面板将保存的页面组织到文件夹中，并通过 MCP 将这些书签暴露给 Agent 注意： - Vessel 通过其本地 MCP 服务器向外部 Agent 暴露浏览器控制 - 默认 MCP 端口是 `3100` - Hermes Agent 和 OpenClaw 应该将 Vessel 视为持久的、可视化浏览器，而不是启动它们自己独立的浏览器会话 - Vessel 支持具有可配置 AI 提供商的内置聊天标签页；打开设置 (`Ctrl+,`) 并启用聊天助手以设置提供商和模型 - 审批策略通过侧边栏监管面板实时控制，而不是单独的全局设置屏幕 - 设置现在显示 MCP 运行时状态、活动端点、启动警告，并允许在立即重启服务器的情况下更改 MCP 端口 - Agent 可以选择性地禁用问题标签页的广告拦截，重新加载，重试流程，并在稍后重新开启拦截 - Agent 可以使用命名会话（例如 `github-logged-in`）持久化认证状态，并在以后的运行中重新加载该状态 - 预期的控制平面是通过 MCP 驱动 Vessel 的外部框架 - 如果你在设置中设置了 Obsidian 库路径，框架可以通过 Vessel 记忆 MCP 工具直接将 Markdown 笔记写入该库 初始记忆工具： - `vessel_memory_note_create` - `vessel_memory_append` - `vessel_memory_list` - `vessel_memory_search` - `vessel_memory_page_capture` - `vessel_memory_link_bookmark` 目前公开的书签和文件夹工具包括： - `vessel_bookmark_list` - `vessel_bookmark_search` - `vessel_bookmark_open` - `vessel_bookmark_save` - `vessel_bookmark_remove` - `vessel_create_folder` - `vessel_folder_rename` - `vessel_folder_remove` 目前公开的页面交互和恢复工具包括： - `vessel_extract_content` - `vessel_read_page` - `vessel_scroll` - `vessel_dismiss_popup` - `vessel_set_ad_blocking` - `vessel_wait_for` - `vessel_screenshot` (高级版) — 将整捕获为图像用于视觉 AI 分析 页面高亮工具： - `vessel_highlight` — 在页面上用带标签的彩色覆盖层视觉标记文本或元素；持续存在直到被清除 - `vessel_clear_highlights` — 从当前页面移除所有高亮 工作流跟踪工具： - `vessel_flow_start` — 开始命名的多步骤工作流并预先声明其步骤；进度在整个执行过程中显示在侧边栏中 - `vessel_flow_advance` — 将当前步骤标记为完成并前进到下一步 - `vessel_flow_status` — 检查当前工作流进度 - `vessel_flow_end` — 清除活动的工作流跟踪器 数据提取工具 (高级版)： - `vessel_extract_table` — 将页面表格提取为带有列标题的结构化 JSON 行 目前公开的命名会话工具包括： - `vessel_save_session` - `vessel_load_session` - `vessel_list_sessions` - `vessel_delete_session` 会话文件是敏感的，因为它们可能包含登录 cookies 和 tokens。Vessel 使用限制性文件权限将它们存储在应用用户数据目录下。 Agent 凭证保管库工具 (高级版)： - `vessel_vault_status` — 检查某个域名是否存在存储的凭证（返回标签/用户名，从不返回密码） - `vessel_vault_login` — 使用存储的凭证填写登录表单（盲填 — 凭证直接进入页面，从不进入 AI 对话） - `vessel_vault_totp` — 从存储的密钥生成并填写 TOTP 2FA 代码 会话性能工具 (高级版)： - `vessel_metrics` — 显示每个工具的调用次数、平均持续时间、错误率和总会话统计 保管库安全模型： - 凭证使用 AES-256-GCM 在静态时加密，密钥由 OS keychain 保护 (Electron safeStorage) - 凭证值**从不**发送给 AI 提供商 —— 它们仅通过主进程流向内容脚本 - 每次凭证使用都会触发用户同意对话框（“允许一次” / “允许会话期间” / “拒绝”） - 所有凭证访问都记录在仅追加审计日志中 - 凭证是域名范围的 —— 它们只能在匹配的域名上使用 - 用户在设置 > Agent 凭证保管库中管理凭证 值得注意的提取模式包括： - `visible_only` — 仅当前可见、在视口内、无阻碍的交互元素以及活动覆盖层 - `results_only` — 仅可能是主要的搜索/结果链接 - `full` / `summary` / `interactives_only` / `forms_only` / `text_only` 提取输出可以区分： - 活动阻止覆盖层 - DOM 中存在但对当前会话或区域不活跃的休眠同意/模态 UI 通用 HTTP MCP 配置： ``` { "mcpServers": { "vessel": { "type": "http", "url": "http://127.0.0.1:3100/mcp" } } } ``` Hermes Agent `config.yaml` MCP 配置： ``` mcp_servers: vessel: url: "http://127.0.0.1:3100/mcp" timeout: 180 connect_timeout: 30 ``` ## 配置 安装程序将两个片段写入： - `~/.config/vessel/mcp-http-snippet.json` - `~/.config/vessel/mcp-hermes-snippet.yaml` 它还安装了一个辅助命令： ``` vessel-browser-mcp ``` 辅助示例： ``` # 通用 JSON 片段 vessel-browser-mcp # Hermes-ready YAML 片段 vessel-browser-mcp --format hermes # 原始 MCP endpoint URL vessel-browser-mcp --format url ``` 源码安装更新辅助： ``` # 检查是否有可用的 source-install 更新 vessel-browser-update --check # 获取、重建并更新本地 source install vessel-browser-update ``` 状态辅助： ``` # 人类可读的本地 install + MCP 状态 vessel-browser-status # 适用于 harnesses 的机器可读状态 vessel-browser-status --json ``` 智能启动辅助： ``` # 使用最佳可用本地 install 启动 Vessel vessel-browser-launch # 显示选定的启动路径而不启动任何内容 vessel-browser-launch --dry-run ``` `vessel-browser-launch` 优先选择健康的源码安装，当源码安装可能被 Electron 沙箱权限阻止时，回退到最新的本地 AppImage。 ## 键盘快捷键 | 快捷键 | 操作 | |----------|--------| | `Ctrl+L` | AI 命令栏 | | `Ctrl+Shift+L` | 切换 AI 侧边栏 | | `Ctrl+Shift+F` | 切换专注模式 | | `F12` | 切换开发者工具面板 | | `Ctrl+T` | 新建标签页 | | `Ctrl+W` | 关闭标签页 | | `Ctrl+,` | 设置 | ## 项目结构 ``` src/ ├── main/ # Electron main process │ ├── ai/ # Agent tools, query flow, and AI provider implementations │ ├── tabs/ # Tab + TabManager (WebContentsView) │ ├── agent/ # Agent runtime, checkpoints, supervision, flow tracking │ ├── content/ # Readability extraction, reader mode, screenshot │ ├── config/ # Settings persistence │ ├── ipc/ # IPC handler registry │ ├── vault/ # Agent Credential Vault (encrypted storage, consent, audit) │ ├── mcp/ # MCP server for external agent control │ ├── devtools/ # CDP session management for Dev Tools panel │ ├── highlights/ # Page highlight capture, injection, and persistence │ ├── health/ # Runtime health monitoring (MCP, settings, ports) │ ├── premium/ # Subscription management, feature gating, Stripe integration │ ├── bookmarks/ # Bookmark and folder persistence │ ├── history/ # Browse history │ ├── memory/ # Obsidian vault hooks │ ├── network/ # Ad blocking, URL safety, link validation, downloads │ ├── sessions/ # Named session save/load/delete │ ├── startup/ # App initialization, menu, shortcuts, renderer bootstrap │ ├── telemetry/ # PostHog analytics (opt-in) │ ├── tools/ # Tool definitions, input coercion, pruning │ ├── window.ts # Window layout manager │ └── index.ts # App entry point ├── preload/ # contextBridge scripts │ ├── index.ts # Chrome UI preload │ └── content-script.ts # Web page preload (readability) ├── renderer/ # SolidJS browser UI │ └── src/ │ ├── components/ │ │ ├── chrome/ # TitleBar, TabBar, AddressBar, AgentTranscriptDock │ │ ├── ai/ # CommandBar, Sidebar (Supervisor/Bookmarks/Checkpoints/Chat/Automate) │ │ ├── devtools/ # DevTools panel (Console, Network, Activity) │ │ └── shared/ # Settings panel │ ├── stores/ # SolidJS signal stores (tabs, ai, ui, runtime, bookmarks, etc.) │ ├── styles/ # Theme, global CSS │ └── lib/ # Keybindings, markdown, automation kits registry └── shared/ # Types + IPC channel constants ``` ## 设计原则 - **Agent 优先** — 浏览器是 Agent 的操作界面，而不仅仅是附加了自动化的人类工具 - **可视化** — UI 应该使 Agent 行为易于跟随、审计和引导 - **默认持久** — 浏览器状态应该在长时间运行的工作流和重复会话中存活 - **内容优先** — 浏览器界面 110px，其他一切都是你的页面 - **护眼** — 温暖的深灰色、柔和的文本、没有视觉噪音 - **Linux 原生** — 无框窗口、系统字体回退、XDG 约定 ## 许可证 MIT *由 Tyler Williams 在俄勒冈州波特兰开发 (2026)*

标签：Agent Runtime, AI 浏览器, AppImage, BYOK, CMS安全, IP 地址批量处理, JavaScript, Linux 桌面应用, MCP 协议, MITM代理, OpenAI API 集成, RPA 工具, Web应用防火墙, Web 自动化, 人机协同, 工作流自动化, 开源浏览器, 持久化状态, 无头浏览器替代, 智能体工具, 暗色界面, 桌面应用开发, 浏览器控制, 浏览器自动化, 状态管理, 网络信息收集, 自主浏览, 自动化攻击