Browser Copilot

English · 简体中文

一个真正会替你操作网页的 AI 助手。打开侧边栏，用大白话说出需求，Browser Copilot 就会读取你正在看的页面并动手操作——点按钮、填表单、滚动、切换标签，一路走完下单、注册、配置等整段流程；你可以在旁边盯着有风险的动作逐个确认，也可以放手让它自动完成。

🧠 用你已经在用的模型。 任意 OpenAI 兼容端点：DeepSeek、火山方舟、OpenAI、 OpenRouter、Moonshot、百炼、硅基流动，或本地 Ollama/LM Studio，自带密钥即可。
🆓 默认就能免费使用。 全新安装默认启用 Pollinations（免密钥、无需配置）。 Gemini、Groq、Cerebras、SambaNova、Chutes、OpenRouter、GitHub Models、智谱 GLM-4-Flash 提供免费额度。
🎚️ 自主程度由你决定。 五种模式，从纯聊天到全自动，另有把一次执行沉淀成工作流的工作流生成模式；半自动只对有风险的动作（付款、密码、删除、发送）先问，读页面和滚动直接执行。
💸 只发这一步需要的工具。 专项页面工具（滚动、按键、表单控件、视觉、脚本）按组按需加载，不再每轮都塞进请求；只读模式则完全不发任何写操作工具——首轮工具 schema 因此缩小了约三分之一。设置里的工具列表按加载分组展示，一眼看清"什么时候加载什么"。
🧩 技能（Skills） 把可复用的经验（评审清单、文案风格、提取格式）存成一键指令，模型必须严格遵循。
🎬 工作流让整套流程自动跑。 录制一遍操作、让助手直接生成，或在可视化画布上用 56 种块搭出流程——点击、填写、循环、条件分支，甚至 AI agent 步骤——然后手动运行、定时运行、浏览器启动时运行、按快捷键触发、从右键菜单触发，或打开匹配页面时自动运行。
🛍️ 通过广场分享工作流。 把任意工作流以 PR 形式发布到公共广场或私有团队仓库；浏览、搜索和排序别人发布的工作流；安装后触发器默认全部关闭；发布者更新后再提醒你升级。
🎯 直接点选元素，不用描述它。 在设置里打开页面元素选择器后，每个页面右下角都会出现准星按钮：点一下即可复制 CSS 选择器、可见文本或 HTML；开启「选中但不复制」时只记录元素，助手或接入的编码 agent 可以用 read_selected_element 读取它。
✍️ 在面板里直接反馈。 设置末尾提供反馈入口：写清问题、可选附带版本/构建/浏览器诊断，不用离开插件就能创建公开的 GitHub issue。
⏰ 能定时干活，睡觉时也不闲着。 任务可以在某个指定日期时刻只跑一次，也可以每隔几分钟、每天、工作日或每周重复——无人值守执行一条指令或跑一个已保存的工作流，保留完整运行记录，还能把本次产出交给链条里的下一个任务。
📊 花了多少 token 看得见。 token 用量看板按今日 / 近 7 天 / 近 30 天 / 使用以来汇总，并按功能、以及按会话、任务与工作流拆分。
🔄 合上面板，回合不断流。 以前最小化面板会关掉它的文档，正在跑的回合只能往已断开的端口里写：重开后面板停在一帧快照上，直到这一回合结束，期间弹出的确认也没人能答。现在输出走会话级通道，重开的面板重新接管它，并补齐你离开期间流过的内容。
💬 从飞书派活、收结果。 任务完成自动推送到群聊；也可以在手机上私聊机器人下达指令，它会在你电脑的浏览器里执行并把结果回复给你。
🤝 编码助手也能驱动它。 Claude Code、Codex、Trae——任何 MCP 客户端——都能通过本地适配器获得一套浏览器工具，直接操作你真实的 Chrome（见 Agent 接入）。
🔒 天生注重隐私。 无需账号、无埋点、没有我们的云服务器；密钥和数据只保存在你的电脑上，密码本地填写、绝不会展示给模型。默认的免费 Pollinations 会把提示词发往 Pollinations；若文本必须留在本机，请改用本地模型或你自己的服务商。
💾 数据就是你硬盘上的文件。 在设置里选一个文件夹，对话、技能、工作流都会以真实文件落盘，不再往浏览器自身存储里写第二份。

它不会自作主张地行动——每个动作要么是在执行你刚提出的请求，要么来自你创建的定时任务，要么来自你搭建并启用了触发器的工作流，要么是你从飞书发来的指令，要么是你在本地接入的编码 agent 通过 MCP 发来的工具调用。

快速开始

1. 安装扩展

需要 Chrome 116+（或任何支持 Manifest V3 侧边栏的 Chromium 浏览器）。 Firefox 128+ 使用单独的 .xpi 构建。

方式一：下载发行版（推荐）

前往 Releases 页面。每个版本提供三种产物，按需选择：
- browser-copilot-<版本>-ocr.zip —— 完整版，内置本地 OCR （Tesseract.js）：工作流的 OCR 识别算子、离线验证码识别开箱即用。
- browser-copilot-<版本>-no-ocr.zip —— 精简版（体积小约 35 MB：不含 Tesseract.js 引擎与语言模型）。其余功能完全一致；OCR 算子置灰不可用。图片文字仍可通过视觉模型识别（更多 → 模型设置 → 图片识别模型）。
- browser-copilot-<版本>-firefox.xpi —— Firefox 128+ 版。它没有经过 Mozilla 签名，请在 about:debugging#/runtime/this-firefox 里用 临时载入附加组件 加载（临时：Firefox 重启后会移除），或在开发者版/ESR 中关闭 xpinstall.signatures.required 后安装。它不会自动更新。
解压到一个会长期保留的文件夹——扩展会从该文件夹加载，之后不要删除它（Firefox 版保留 .xpi 文件本身即可）。
打开 chrome://extensions。
打开右上角的开发者模式开关。
点击加载已解压的扩展程序，选择解压出来的文件夹——即直接包含 manifest.json 的那一层。
点击工具栏上的扩展图标打开侧边栏；建议把它固定到工具栏方便使用。

方式二：从源码构建

需要 Node.js 20+ 和 pnpm（或 npm）。

git clone [email protected]:dcc123456/browser-copilot.git
cd browser-copilot
pnpm install
pnpm run build

然后在 chrome://extensions（开启开发者模式）点击加载已解压的扩展程序，选择构建出来的 dist/ 目录。以后拉取新代码后，重新执行 pnpm run build，并在扩展卡片上点重新加载——仅重新构建不会刷新已加载的 service worker。

更新已有的安装

数据跟着扩展 ID 走，而不是跟着版本走：只要扩展 ID 不变，设置、工作流、对话、任务和权限授权都保留。未打包扩展的 ID 由安装目录的绝对路径派生（本项目的 manifest 没有固定 key），因此把新文件覆盖进当初加载的那个目录是安全的；把新安装包解压到另一个目录再加载，会得到第二个空的扩展。

0.6.8 及以后——自动更新：

扩展每 12 小时检查一次 GitHub Releases；打开面板时如果发现状态已过期也会自动补检。检测到新版本后，侧边栏会出现横幅，点更新；也可以走 设置 → 更新 → 检查更新。
第一次更新会让你选择当初加载的目录（直接包含 manifest.json 的那一层），并请求一次写入权限；之后的更新自动复用，不再询问。
它会下载与当前变体一致的安装包，校验发布包的 SHA-256 摘要，把将被替换的文件备份到安装目录里的 browser-copilot-backup-<旧版本>-<时间戳>/ （备份里的清单命名为 manifest.json.bak，不会被误当成第二个扩展加载），再写入新版本。在你选择立即重新加载之前，Chrome 始终运行旧版本；选稍后则文件已就位，横幅会保留提醒。
备份会在新版本重新加载后下次打开面板时自动删除——能打开面板就说明新版本已经跑起来了。（删除需要当次浏览器会话仍持有该目录权限；否则备份保留，之后打开面板时会再试。）也可以提前手动删除。自动更新只跟随你已安装的变体（ocr / no-ocr），也不会触碰任何已存数据。

0.6.7 及更早——手动替换一次，之后交给自动更新： 0.6.8 之前的版本没有更新器，需要就地替换一次文件：

找到扩展当初加载的目录——安装时解压出来的、直接包含 manifest.json 的那一层文件夹。
下载同一变体的新安装包，解压到一个临时目录。
关闭侧边栏，把旧目录里的内容替换成新版本的内容：先删掉旧文件再复制，或直接覆盖并选择「替换」。保留这个文件夹本身和它的路径，不要改名或移动。
打开 chrome://extensions，在 Browser Copilot 卡片上点重新加载。 不要点「移除」——移除扩展会一并删除它的已存数据。
打开侧边栏，在设置 → 更新里确认版本号。从此以后新版本由自动更新处理。

不要在新旧两个目录各装一份，也不要移动或重命名已加载的目录：两种做法都会改变派生出的扩展 ID，Chrome 会把它当成另一个扩展，旧数据仍藏在旧 ID 下、看起来像丢了。如果你配置过存储位置（设置 → 存储位置），工作流和对话就是那个文件夹里的真实文件，无论如何都不受影响；替换后可能需要重新授权一次该目录。

要在 ocr 与 no-ocr 两个变体之间切换，请走上面的手动替换——自动更新只跟随当前已安装的变体。Firefox 版不会自更新；按发行说明里的「从文件安装」流程重装即可。

2. 添加模型

打开侧边栏 → 更多 → 模型设置 → 添加模型服务。

选一个预设——接口地址和建议模型会自动填好（DeepSeek、火山方舟、OpenAI、 OpenRouter、Moonshot、百炼、硅基流动、Ollama 等）；也可选自定义接入任意 OpenAI 兼容端点。
粘贴 API 密钥。本地 Ollama/LM Studio 填任意非空字符串即可。
填模型——手动输入模型 ID，或点获取模型列表让端点返回可用模型（即使网关没有 /models，手动输入也始终有效）。
点测试连接——它会发一次真实请求，同时验证密钥和模型是否都可用。
保存。可以添加任意多个服务，用使用这个在它们之间切换，也可以直接在聊天输入框旁的模型选择器里切换。每个配置还能设置思考强度（跟随服务商默认、关闭、低、中、高），适用于支持该参数的模型。

模型必须支持 function calling（工具调用）。不支持的话，助手只能聊天，无法主动读取或操作页面。日常可靠选择有 deepseek-chat、gpt-4o-mini、qwen-plus；难任务用推理模型，隐私敏感用本地模型。

3. 选择自主程度

用聊天框左下角的下拉框选择。选择作用于下一个动作，即使回答进行中也能切换：

💬 聊天——纯对话，不读取也不操作页面（最省 token）。
🔒 只读——只能读取；所有写操作工具都不发给模型，因此不点击、不输入、不跳转、不填写。
🛡 半自动（默认）——只有有风险的动作才等你一键确认：付款或提交订单、填写密码或验证码、删除或重置、发送或发布、脚本，以及创建技能或定时任务。读页面、滚动、等待、导航和认得出名字的普通点击会直接执行。
⚡ 全自动——动作不再确认直接执行。
🧩 工作流生成——边执行边学习任务：真正成功的每一步都会变成工作流草稿里的节点，回合结束时保存为工作流。它不是演练——算子会真的点击、输入和跳转， JavaScript 块也会真的执行页面代码。

4. 开始提问

输入后按 Enter 发送（Shift+Enter 换行；使用中文/日文/韩文输入法时，第一次回车确认候选词、第二次才发送）。

勾选附带选中内容，发送你在页面上高亮的文字（只发选区，不发整页）。
在输入框打 / 可选择技能或命令，例如 /compact 立即压缩上下文。
打 @ 可附带文件（图片 ≤ 4 MB、文本 ≤ 200 KB；每条消息最多 4 个、合计 8 MB）。
选中技能后甚至可以发空消息——它会把技能应用到你的输入或选中内容上。
发送按钮旁的模型选择器可直接切换下一条回复使用的模型，不必打开设置。

回复以 Markdown 渲染。可以随时关闭面板，回答会在后台继续；重新打开会补齐你离开期间跑掉的步骤，中途提出的确认也照样能答。

能用来做什么

最适合"任务发生在一个页面上、又需要读和操作结合"的场景：

填写表单：套用已保存的资料；密码会直接填进字段，模型自始至终看不到密码值。
走完多步流程：加购物车、结账、改设置——半自动逐步确认，全自动一路执行。
评审 PR、看懂代码/文档：先选中关心的那段，给模型一个精确目标而不是整页。
总结长文章、文档、release notes、长帖。
分析页面数据：但模型是在对文本推理而不是计算，长表格里的数字请当作待验证的假设。
配合技能套用可复用的标准（评审规范、文案风格、检查清单）。

它做不到：在聊天或只读模式下操作页面；读取 chrome://、本地文件或应用商店页面；解验证码或绕过二次验证；保证长表格算术正确；在浏览器完全关闭时运行任务（定时任务只在浏览器开着时触发）。

代理模式

下拉框的选择作用于下一个动作，即使回答正在进行中也能立即切换。

模式	行为	适用场景
💬 聊天	纯对话。不向模型发送读页面或操作工具，因此不会碰页面，token 消耗最低。仍可附带选中的文字。	头脑风暴、写作、问答、翻译——不希望它操作页面时。
🔒 只读	只能读取。所有写操作工具都不发给模型，因此不点击/输入/跳转/填写。	评审、总结、翻译——零副作用。
🛡 半自动（默认）	只对有风险的动作先问：付款、密码/验证码、删除、发送、脚本、持久化写入。读页面、滚动、导航和认得出名字的普通点击直接执行。	日常使用；把可控留给真正重要的动作。
⚡ 全自动	动作不再确认直接执行。	你信任的、重复性流程。
🧩 工作流生成	与全自动一样真实驱动页面，但只有真正成功的步骤才会变成工作流草稿节点，不逐步确认；回合结束时提示保存草稿。	把一段能用语言描述的任务沉淀成可复用工作流。

半自动下确认卡片会准确显示要点哪个按钮、填哪个字段、打开哪个 URL；认不出是什么的元素会被当作有风险而先询问，而不是猜。全自动下每个动作仍记录在数据标签的操作历史里，事后可审计。工作流生成不是演练：算子会真的点击、输入和跳转， JavaScript 代码块会在页面里执行任意代码——只用在你信任的网站上，并在运行生成的 workflow 前先审阅它。

模型

任何遵循 OpenAI chat-completions 协议的端点（POST {baseUrl}/chat/completions、Bearer 认证、SSE 流式返回）。provider 只是配置，不是代码分支，没列出的端点同样能用。

预设	接口地址	模型示例
DeepSeek	`https://api.deepseek.com/v1`	`deepseek-chat`、`deepseek-reasoner`
火山方舟 Ark	`https://ark.cn-beijing.volces.com/api/v3`	`doubao-seed-code`，或 `ep-…`
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini`
OpenRouter	`https://openrouter.ai/api/v1`	`deepseek/deepseek-chat`
Moonshot / Kimi	`https://api.moonshot.cn/v1`	`kimi-k2-0905-preview`
阿里云百炼 DashScope	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-plus`
硅基流动 SiliconFlow	`https://api.siliconflow.cn/v1`	`deepseek-ai/DeepSeek-V3`
Ollama（本地）	`http://localhost:11434/v1`	`qwen3:8b`
LM Studio（本地）	`http://localhost:1234/v1`	`local-model`

免费选项：全新安装默认已启用 Pollinations。设置 → 模型服务里只有直接免费用 （无需密钥）的提供商会进入免费可用分组；有免费额度/每日赠送的提供商留在全部服务，其免费模型仍显示 Free 标签。

免费预设	接口地址	说明
Pollinations	`https://text.pollinations.ai/openai`	直接免费——无需密钥；匿名档有限流，支持工具
Google AI Studio (Gemini)	`https://generativelanguage.googleapis.com/v1beta/openai`	用 AI Studio key 的免费额度
Groq / Cerebras / SambaNova	各自端点	用 key 的免费额度；工具支持因模型而异
Hugging Face	`https://router.huggingface.co/v1`	用 HF token 的每月免费额度
ModelScope 魔搭	`https://api-inference.modelscope.cn/v1`	用 ModelScope token 的免费额度
Together AI	`https://api.together.xyz/v1`	免费模型以 `-Free` 结尾（免费额度）
Novita / Nebius / Fireworks	各自端点	用 key 的免费起始额度
OpenRouter	`https://openrouter.ai/api/v1`	免费模型以 `:free` 结尾（免费额度）
GitHub Models	`https://models.github.ai/inference`	用 GitHub PAT 的免费额度

聊天输入框的模型选择器里，免费模型统一显示 Free；混合目录只标免费系列（OpenRouter :free、Together -Free、智谱 glm-4-flash），付费模型不标。

DeepSeek 与 OpenAI 的官方 API 是收费的；免费 DeepSeek/GPT 访问来自上面的免费额度。

怎么选：要让它自主读页面/动手，必须选支持工具调用的模型。日常用便宜快的（deepseek-chat、gpt-4o-mini、qwen-plus），难任务用推理模型，敏感内容用本地模型。页面文本上限约 12,000 字符，长页面优先选大上下文模型。

可添加多个服务，用使用这个切换，也可以从聊天输入框的模型选择器直接切换；密钥按配置分别保存。每条回复最多操作步数（默认 20，范围 1–100）是一批而不是终点：面板聊天最多自动续跑十批（默认即 200 步）才触及安全上限，每个检查点都会重新启用上下文压缩；定时任务和 AI agent 块仍只跑一批。密钥保存在本机（选定存储文件夹后即为磁盘文件；不同步、不加密），不能接受请改用本地模型。

使用说明

窗口作用域：所有由面板发起的操作（读取/操作页面、新开/切换/关闭标签、从面板运行工作流）只作用于打开面板的那个浏览器窗口；定时任务、飞书指令等无人值守任务在面板开着时也同样锁定该窗口。你可以再开一个没有面板的窗口自己随意使用——它不会被读取、不会被操作，也不会触发"打开匹配页面时自动运行"的工作流触发器。只有在任何窗口都没有打开面板时，无人值守任务才按原有全局逻辑运行；键盘快捷键和右键菜单在工作流发生的那个窗口生效。
读取页面：要么勾选附带选中内容直接发送高亮文字，要么让助手自己读取。读页面属于观察性操作，不会先确认——只读和半自动下都是如此；只有有风险的动作才会询问。
附带选中内容只采集 window.getSelection()，发什么由你精确控制。
Markdown：回复渲染标题、列表、表格、带复制按钮的代码块；你自己输入的内容保持原样。
元素选择器：在更多 → 设置 → 元素选择器里打开后，每个网页右下角会出现准星按钮。点它进入选择模式，悬停高亮、点击锁定：会把 CSS 选择器、可见文本或 HTML（含子元素）复制到剪贴板，同时把该元素记录给助手。开启选中但不复制时只记录不复制——助手或本地 agent 可以通过 read_selected_element 读取它的选择器、标签、文本和截断后的 HTML；在别的 URL 上做的选择会标记为过期。工作流编辑器里的选择器是另一套工具，仍保留卡片。
长对话：下一次请求接近模型上下文窗口时，较早的回合（助手回答与工具往返）会被一段摘要替换，你自己的消息和最近的回合保持原文；输入 /compact 可立即压缩。
token 用量：更多 → token 用量是用量看板，可按今日 / 近 7 天 / 近 30 天 / 使用以来查看，支持折线图和表格两种视图，并按功能（聊天、工作流生成、工作流运行、AI 调试、自动修复、定时任务、上下文压缩、视觉识别、外部 API）以及按会话、任务与工作流拆分。Runner 自己的开销不在这个看板上，走它的 HTTP 接口读取。
语言与主题：设置 → 语言（English / 简体中文 / 自动）；面板跟随系统浅色/深色主题实时切换。
存储位置：设置 → 存储位置可选一个磁盘文件夹，之后所有数据都会以真实文件写入该目录（详见保存的数据与隐私）；未选择前数据保存在浏览器存储里。定位动作会在系统文件管理器里打开该文件夹，另有一项直接打开浏览器的默认下载文件夹。
安装信息：设置里展示版本号、安装类型（未打包或商店版）、扩展 ID，以及打开该扩展 chrome://extensions 卡片的链接；未打包安装还可以直接打开源码目录。
历史：时钟图标打开历史对话，可继续、预览、重命名、删除。会话保存在本机（每条保留最新 200 条消息）——选定存储文件夹后即为磁盘上的真实文件。
反馈：更多 → 设置末尾的反馈与建议可以写报告、可选附带诊断信息（扩展版本、构建号、浏览器与界面语言——不含页面 URL 或凭据），并创建公开的 GitHub issue。它使用和工作流广场相同的 classic GitHub 令牌；没有令牌时可在弹窗里直接连接。

技能（Skills）

技能是一段存下来的指令包，把提示词里不变的部分固定下来。在技能 → 新建技能里填名称、一句话适用场景和具体指令。然后二选一：在输入框打 / 手动选择，或保持"允许 agent 自动应用"开启，让它在消息匹配时自行使用。

技能一旦被选中，会被强制应用到该轮：完整指令注入系统提示词，用户消息也被绑定为按该技能处理，模型无法绕过技能作答。前期只提供名称和说明，完整指令按需加载。

技能像通用技能一样以文件保存。 每个技能对应一个以其 slug 命名的文件夹，内含一份 SKILL.md：YAML frontmatter（name、description、autoMatch 等）+ Markdown 正文指令。选定存储文件夹后，它们位于磁盘上的 skills/<slug>/SKILL.md，你可以直接手改，Browser Copilot 会读取最新内容；未选文件夹时回退到浏览器存储。

工作流

工作流标签把一套可重复的浏览器操作变成保存下来、可反复运行的自动化——在可视化画布上搭建的节点图，设计上对齐 Automa。在该标签创建工作流，点编辑会在独立标签页打开完整的流程编辑器。

四种创建方式：

录制：在编辑器里点录制，把任务做一遍。点击、表单输入（文本/下拉/复选/单选）、滚动、切换标签、新开标签、整页跳转和 SPA 路由变化都会被捕获成块——包括等待元素出现/等待页面加载的停顿。停止录制后，流程自动变成画布上的工作流；如果画布已经打开，录制的步骤会接在末端节点之后，而不是另存一份工作流。
生成：把聊天模式切到 🧩 工作流生成，用语言描述任务：真正成功的每一步都会变成草稿节点，回合结束时弹出保存工作流的卡片。生成的工作流可以先真实运行一次做验证；某一步失败时 AI 修复会提出修改，只有在独立运行通过后才会保存。
聊天转换：一轮聊天里实际操作过页面后，可以把已执行的动作保存为工作流，之后不再经过模型也能复用。
手动搭建：从块面板拖出节点、连线即可。

分组。 工作流标签里可以把工作流归档到分组。分组标题上的加号会在该组内直接新建工作流，选中的工作流可以批量移动；删除分组会连同组内工作流一起删除——确认框会写明分组名和数量。

块里有什么。 从 Automa 移植的 56 种可执行块：点击/悬停/滚动元素、填表、读文本、判断元素存在、按数据或元素循环、while/重复执行、条件分支、变量与 {{token}} 插值、JavaScript 代码、 Cookie、Webhook、剪贴板、截图、下载处理、新建/切换/刷新/关闭标签、延时等。（Automa 的 5 个云块——Google 表格/云盘、块包、云端 AI 工作流——仅为兼容而列出，不可执行。）每种块都有专属编辑表单，可以单独停用，也能配置自己的错误处理：失败时重试或改走另一条分支。

精确定位目标。 内置元素选择器可为任意目标生成 CSS 或 XPath 选择器——悬停高亮、点击锁定、在 DOM 里上下行走、CSS/XPath 一键切换。位于闭合 shadow DOM 内部的目标可通过 Chrome DevTools Protocol 点击。画布支持一键自动布局；Ctrl+S 保存，Ctrl+Enter 运行。

在编辑器里工作。 画布与磁盘内容不一致时保存按钮会显示标记；底部工具条提供撤销/重做/ 自动布局，数据表标签列出每个运行期变量的写入者与读取者，并可跳转到对应节点。画布上还有一个 AI 助手，能按提示词编写算子并展示推理过程；工作流可以声明目标，验证运行会报告是否在没有 AI 接管的情况下达成目标。

一个特殊块：AI agent。 它把这一步交给与聊天相同的 agent 循环——只读模式下它读取页面（或指定元素）并回答、不做任何操作；全自动模式下它可以点击和跳转。回答会存进输出变量，供后面的块插值使用。它的表单里有技能与工具折叠区：工具默认开启、可逐个关闭，技能默认关闭、需逐个开启，关闭的内容不会再进入模型请求。九个会改变状态的工具——关闭/固定/取消固定标签、保存文件、创建技能、列出和创建定时任务、展示计划、委派子 agent——不会提供给 AI agent 块。

触发方式。 工作流在触发器生效时运行：

手动——编辑器或工作流标签里的运行按钮；
定时——与定时任务相同的排程选项（一次、每隔 N 分钟、每天、工作日、指定星期，或五段式 cron 表达式）；
浏览器启动时、键盘快捷键（每个工作流可自定义，如 Ctrl+Shift+E）、右键菜单、或打开 URL 匹配指定模式的页面时。

查看运行。 历史标签的活动板统一展示工作流与任务的运行中和已完成记录——实时进度、按块日志、调试模式、中途取消。工作流标签显示每个工作流的上次运行状态，失败的运行可一键直达其日志。

失败重试。 两个层级：

单个块。 每个块的「出错时」设置可以让它自己重试 N 次（含间隔），或改走 fallback 分支。适合偶尔失灵的一次点击。

一组步骤。 把整组步骤放进重复任务块里，用元素是否存在判断是否失败 ——比如登录时验证码输错就刷新重来、最多尝试 5 次：

重复任务 (5)
 ├─ loop → 点「刷新验证码」→ OCR 识别验证码图片（→ lastOcrText）
 │          → 验证码输入框填 {{lastOcrText}} → 点「登录」→ 等待 2 秒
 │          → 元素是否存在（错误提示选择器）
 │                         ├─ 存在（失败）  → 连回「重复任务」块 = 下一次重试
 │                         └─ 不存在（成功）→ 设置变量 loginOk=true
 │                                            → 循环断点
 └─ end  → 条件（loginOk 是否存在）─ 成立 → 登录后的后续步骤…
                                   └ 不成立 → 5 次均失败的处理

循环体是挂在 loop 出口上的那串块；把体内最后一个块连回循环块即结束一次迭代。循环断点用于提前跳出；执行会从循环块的 end 出口继续——该出口在循环自然跑完后同样会走到，所以用变量 + 条件块区分两种结局（如上），例如始终登录失败时发通知或让运行判失败。（替代做法：手工把块连成环、用「变量自增」+「条件」做重试计数——也能跑，但没有上面的循环结构清晰。）

导入导出。 支持导出单个或全部工作流为 JSON，并可导入 JSON——包括从 Automa 导出的文件。旧版工作流格式在加载时自动迁移。

分享。 工作流卡片上的发布操作会向公共广场或已连接的团队仓库提交 PR——见工作流广场。

工作流广场

工作流广场（在更多菜单里）通过 GitHub 分享工作流，不需要额外服务器。它有两个来源：

公共——项目公共仓库里的所有 listing。应用一张卡片前会先让你确认该工作流可以操作页面，然后保存一份本地副本，并关闭全部触发器；在你手动启动前它不会运行。再次应用会复用这份本地副本，不会堆出重复工作流。
团队——在更多 → 设置 → 团队共享里连接的私有仓库，每个仓库用自己的 classic GitHub 令牌（需要 repo 权限；团队常常分属不同 GitHub 账号）。团队视图会读取所有已连接的仓库并合并结果，可按仓库筛选；某个仓库读取失败时只丢弃它自己的卡片，并在横幅里点名。

支持搜索、分类筛选和排序（最近更新 / 最多点赞）。点赞和评论借助 PR 的 reaction 与讨论线程，每张卡片都带 GitHub 链接。

发布。 工作流卡片的发布操作会打开弹窗，填写标题、描述、分类、标签、可选视频链接、最多 3 张截图和最多 3 个附件（每个 200 KB）。目标可选公共广场或任一已连接仓库——弹窗会默认回到上次发布到的仓库，草稿按目标分别保存，中途关闭也不会丢。调用其他工作流的工作流会作为 bundle 一起发布；使用了已存凭据的工作流会列出凭据名与字段名并随 listing 提交。发布会打开一个 PR：令牌有写权限时，你自己的发布会自动合并且立即上线；第三方发布者仍保留 PR 供审核。对已有 listing 再次发布会更新它；下架会提交删除 PR，已安装的副本不受影响。

应用与更新。 带 bundle 的 listing 会创建一个以父工作流命名的分组，把父工作流和它调用的子工作流一起归档；随 listing 携带的凭据会在保存工作流之前导入。已安装的工作流在发布者更新后显示可更新——新版本，或同一版本但内容哈希变化。更新会替换步骤、触发器和设置，同时保留本地 ID、分组和创建时间。

定时任务

任务标签可以让助手在你设定的时间无人值守地运行——不用开着面板、不用点按钮。创建一个任务，选择做什么、什么时候做，浏览器开着时它就会自动执行。

能做什么：

运行一条助手指令（agent prompt）——把一段指令存下来，助手会像你在聊天里发送一样执行它，包括按当前模式读取或操作页面。适合做定期检查、每日摘要、自动填写并提交等流程。
运行一个已保存的工作流——和工作流页的"运行"走同一套回放，只是按排程触发。
统计 GitHub 上待你评审的 PR 数量——内置任务。
任务可以串成链条：一个任务声明它交出的产出、以及它跟随哪个任务，之后的指令里就能写 {{upstream.<字段>}}。引用在子任务自己运行时才取值，取的是上游最近一次成功运行的产出—— 所以后续任务可以在输入还不存在时就建好（比如给一篇还没发布的笔记，先排好"发布后评论"的任务）。

什么时候运行（使用 Chrome 的 chrome.alarms，最短 1 分钟）。一个任务可以同时配置 多个触发方式；每一项都会挂自己的 alarm，也就是多一种定时运行：

在指定的日期时刻只跑一次（触发后立即解除，不会变成每天跑）；
每隔 N 分钟；
每天固定时间；
工作日（周一至周五）固定时间；
每周指定某几天固定时间；或
五段式 cron 表达式（如 0 9 * * 1-5），按本地时间求值；非法文本会阻止保存，永远不会命中的组合会保持未启用并给出提示。

运行参数只有一个入口：任务的 variables 键值袋。 它由聊天里的 agent 通过 create_scheduled_task 写入，链条里的子任务还能把某个值填成 {{upstream.<字段>}}。

工作流任务：这一袋原样作为本次运行的变量送进引擎，并且覆盖工作流触发节点声明的默认值——画布上记录的 {{字段}} 引用就是在这里取到值的。
指令任务：只有指令文本参与插值，而插值字典里只有 {{upstream.*}}（上游最近一次成功运行声明的产出）；任务自己的 variables 不会被注入到对话上下文。

面板的任务弹窗没有参数输入框：既看不到 variables，也改不了它。但弹窗保存的是整条任务记录，所以 agent 写好的 variables / outputs / followsTaskId 在你改名字、改时间之后仍然保留。由工作流自己的触发节点启动（不经过任务）时只带声明的默认值——排程本身不携带参数。 create_scheduled_task agent 工具支持同样的排程，包括 kind: "cron"。

每次运行都会记录在最近运行里：开始时间、结果、执行步骤和摘要，也可以中途终止——工作流或任务运行时，它的卡片会把立即运行换成终止，一次停掉该项的全部进行中运行。任务只在 浏览器开着时触发（由 alarm 唤醒 service worker），Chrome 关闭时不运行。打开"完成时通过飞书通知"即可把结果推送到飞书。聊天里新建的任务会立刻出现在列表中，点编辑会弹窗修改。

飞书接入

Browser Copilot 能以两种相互独立的方式接入飞书，都在任务标签配置：

主动通知（自定义机器人 webhook）。 填入飞书群自定义机器人的 webhook 地址（以及可选的签名校验密钥），任何任务完成后都可以把结果发到那个群。不需要应用凭据，是"完成后告诉我一声" 最简单的方式。
接收指令远程控制（自建应用 + 长连接）。 填入飞书自建应用的 App ID 和 App Secret 并开启机器人，你就可以在飞书上给机器人发消息，它会把你的消息当作一条助手任务在你这台机器上执行，并把结果回复给你——相当于从手机或另一台设备远程驱动浏览器。

飞书连接由一个看门狗 alarm 保活，断线会自动重连。没有填应用凭据时，通知仍可用，但无法接收指令。

Agent 接入（MCP）

侧边栏不是唯一的入口。开启本地 Agent 接入后，Browser Copilot 会通过 MCP 向同一台机器上的编码 agent 暴露一组浏览器工具——Claude Code、Codex、Trae 或任何 MCP 客户端都行。agent 由此可以打开网址、读取页面、点击、填表、按键、切换标签页、执行 JavaScript、识别验证码文字、保存文件——都发生在你真实的 Chrome 里，"改完代码、回浏览器验证"从此在一段对话里完成。

Claude Code / Codex / Trae   （MCP 客户端）
     │  stdio · JSON-RPC 2.0 —— 适配器由 agent 自动拉起
     ▼
mcp-server.mjs   （零依赖 Node 适配器，随插件内置、设置卡片一键导出）
     │  WebSocket · ws://127.0.0.1:8765   （仅回环）
     ▼
Browser Copilot 插件   （在你的 Chrome 中实际执行每个调用）

环境要求：Node.js ≥ 18，且 Chrome 已加载本插件。适配器是一个零依赖文件 mcp-server.mjs，已内置在安装包中——无需克隆源码或单独下载：在设置卡片上点一次「导出适配器」，它会保存到下载目录的 browser-copilot/ 下，配置片段也会自动填入该绝对路径。从源码构建的用户也可以直接使用仓库里的 public/mcp-server.mjs（构建后位于插件根目录），文件不必放在插件目录里。

手动配置，三步：

插件侧边栏 → 设置 → 本地 Agent 接入 → 打开开关。适配器地址保持 ws://127.0.0.1:8765，可设置一个共享令牌；链路打通后卡片会显示已连接。
在同一卡片点「导出适配器」，然后复制 Claude Code / Codex / Trae 的现成片段 ——片段里的绝对路径已自动填好（插件升级后重新导出一次即可）。
启动（或重启）你的 agent——它通过 stdio 自动拉起适配器，插件自动连上。无需常驻进程、无需 npm install、无需 Python。

🤖 让 AI 替你接线。 复制下面这段提示词，整段发给你的编码 agent（Claude Code / Codex / Trae 均可），AI 会引导你导出适配器并完成全部接入：

请帮我完成 Browser Copilot 插件的 MCP 接入。先在插件侧边栏「设置 → 本地 Agent 接入」
里打开开关，并点「导出适配器」把 mcp-server.mjs 保存到下载目录（browser-copilot/）；
检查 Node.js 环境、向我询问可选共享令牌、用导出文件的绝对路径为你的客户端写入 MCP
配置（卡片上有 Claude Code/Codex/Trae 现成片段可复制），最后用一次真实调用验证整条
链路并汇报结果。完整安装指引在源码仓库的 examples/local-agent/MCP-SETUP-PROMPT.md
（https://github.com/dcc123456/browser-copilot/blob/main/examples/local-agent/MCP-SETUP-PROMPT.md），
找不到时不要臆测路径。

想先看看 AI 会读到什么？提示词全文在 examples/local-agent/MCP-SETUP-PROMPT.md。

工具以 browser-copilot 的 MCP 工具出现（read_current_page、snapshot_page、 read_selected_element、click、fill、open_url、run_javascript、 recognize_image、get_secret、use_skill 等）。页面元素选择器开启选中但不复制 后，你点选的元素可供 read_selected_element 读取——选择器、标签、可见文本和截断后的 HTML，并附带可直接用于 click / fill 的 target；在别的 URL 上做的选择会标记为过期。安全方面：适配器只绑定回环地址；可选共享令牌挡住本机其它进程；密码经 get_secret 填入、值从不进入模型；你在插件里禁用的工具即使被请求也会被拒绝。完整的工具清单、各客户端配置示例和故障排查见 examples/local-agent/README.md，Claude Code 的详细手册见 examples/local-agent/CLAUDE-CODE.md。

保存的数据与隐私

数据标签保存：可填写的资料（姓名/邮箱/电话/地址）、密码（通过 get_secret 直接填入字段，绝不把值返回给模型）、操作历史（每次点击/填写/滚动/跳转，带时间戳和站点）。所有内容都保存在本机——不同步、不发给模型，密码静态存储时不加密。

存储位置。 默认数据保存在 Chrome 的 chrome.storage.local。打开设置 → 存储位置，选一个文件夹（通过 File System Access API）即可改为写入磁盘上的真实文件。此后所有数据都会写进你选定目录下的 browser-copilot/ 文件夹：

conversations/<id>.json — 对话记录；
skills/<slug>/SKILL.md — 技能，每个技能一个文件夹；
<key>.json — 其他所有内容：设置、模型服务、工作流、资料、凭据等。

选定文件夹后就不再往 chrome.storage.local 写数据，它 10 MB 的配额也就不再是上限。唯一还会落到那里的是「文件夹暂时不可用」期间的写入——例如浏览器重启后、你还没重新授权时；这些数据可以从那里读回，并会在下次打开侧边栏时推送到文件夹。随时可以在同一设置卡片切回浏览器存储：切回前会先把文件夹里的数据拷回去，不会留下内容。第一次选择文件夹时会把已有数据迁移过去。

权限	用途
`storage`	保存设置、模型服务、技能、对话、工作流、资料和凭据。
`unlimitedStorage`	解除 `chrome.storage.local` 的 10 MB 上限，保证长对话和大量工作流仍能保存。
`tabs`	识别当前标签页，并在你要求时打开/切换/关闭标签（工作流的标签块也需要）。
`scripting`	注入页面内核、工作流录制器、元素选择器和快捷键监听，以读取或操作标签页。
`sidePanel`	显示侧边栏。
`alarms`	唤醒 worker 运行定时任务和工作流，并在开启飞书时为飞书连接保活。
`offscreen`	运行隐藏文档，让工作流的剪贴板块读写系统剪贴板。
`contextMenus`	添加右键菜单项，启动配置了右键菜单触发器的工作流。
`webNavigation`	侦测页面跳转，用于 visit-web 工作流触发器和录制。
`cookies`	工作流的 Cookie 块读取/设置/删除 Cookie。
`downloads`	工作流的下载处理块观察和管理下载。
`clipboardRead`	读取系统剪贴板，供工作流的剪贴板块使用。
`debugger`	通过 Chrome DevTools Protocol 点击闭合 shadow DOM 内的元素。
`http(s)` 主机权限	与页面交互、请求你配置的模型端点，以及开启时请求飞书。

没有常驻 content script——在某轮回答、某个定时任务或某个工作流需要之前，不会向任何页面注入内容。录制工作流、使用元素选择器或启用键盘快捷键触发器期间，会向打开的标签页注入一个只为该目的服务的小监听器，停止后即移除。alarm 只运行你创建的任务和工作流触发器（以及开启飞书集成时的保活看门狗）。debugger 权限只在工作流需要点击闭合 shadow root 内部时使用。只有你的消息和你附带/批准的页面文字会离开本机，发往你自己配置的端点；任务结果也只有在你开启时才会发送到飞书。没有埋点、没有统计、本项目不存在任何服务器。

开发

pnpm install
pnpm run dev         # 改动即重新构建
pnpm run typecheck   # tsc --noEmit
pnpm run test        # vitest
pnpm run build       # 生产构建输出到 dist/
pnpm run build:no-ocr  # 精简版构建（不含本地 OCR）输出到 dist-no-ocr/
pnpm run build:firefox # Firefox 构建输出到 dist-firefox/
pnpm run package     # 构建全部产物 → releases/browser-copilot-<版本>-ocr.zip
                     #                  + releases/browser-copilot-<版本>-no-ocr.zip
                     #                  + releases/browser-copilot-<版本>-firefox.xpi

把 dist/ 作为已解压扩展加载，改动后在扩展卡片上点重新加载。用 npm 也可以。推送 tag 会运行 .github/workflows/release.yml，执行类型检查、测试、构建，并把三个可加载产物（完整版 -ocr、精简版 -no-ocr 与 Firefox .xpi）挂到 Release。

关键设计：Markdown 解析成类型化语法树（绝不生成 HTML，没有 dangerouslySetInnerHTML）；页内内核自包含并跨框架注入；选定存储文件夹后，持久化状态写入磁盘真实文件（chrome.storage.local 只保留尚未能写入文件夹的暂存数据），即使 MV3 service worker 空闲被回收也不丢数据；模式和步数上限按每个动作读取，改设置无需重新加载。

服务器运行器

想把这个项目的工作流放到远程服务器上无人值守运行（HTTP API / cron 定时 / Webhook / 飞书触发，支持嵌套子工作流复制校验、持久化 profile、CDP 远端浏览器与 Docker 部署），见 docs/server.md。扩展本身不受影响。

执行 pnpm --dir server build 后，runner 会在 http://<服务器>:8787/ 直接托管一个 Web 控制台：配置大模型 / 飞书 / Token / 浏览器参数，导入与在线编辑工作流 JSON，管理定时任务，运行工作流并查看逐步日志——日常运维不再需要敲命令行（CLI 用法全部保留）。

常见问题

现象	处理
提示未配置模型服务	更多 → 模型设置 → 添加模型服务。
401 / 403	密钥错误/过期，或密钥与厂商不匹配。
发送时 404	接口地址少了版本段，或模型名不存在；点测试连接定位。
提示无法读取此页面	`chrome://`、`file://`、应用商店或其他扩展页面，无法注入。
全自动下仍弹确认	重新加载扩展，再确认下拉框显示 ⚡ 全自动。
提示 "Stopped after N tool rounds"	触及安全上限（聊天十批；任务或 AI agent 块一批），发"继续"或调高每条回复最多操作步数。
能聊天但从不读页面或动手	模型不支持工具调用；手动附带页面或换模型。
页面文字为空或不全	内容在 iframe、懒加载，或在"加载更多"后；先选中关键部分。
点工具栏图标没反应	重新加载扩展，可能是 worker 启动失败。

已知限制

一次聚焦一个标签页；大范围读取看到的是已渲染 DOM（iframe 按动作定位）。
面板发起的操作锁定在面板所在窗口内：若该窗口当时只有 chrome:// 等不可操作页面，助手会报"插件窗口内没有可操作的网页标签页"，而不会跨窗口去操作别的窗口。
页面文本上限约 12,000 字符，截断会告知模型。
面板聊天按配置的步数上限成批执行，最多十批（默认即 200 步）后停止；定时任务和 AI agent 块只执行一批。
工作流广场与更新检查共用 GitHub 匿名 API 配额；刷新被限流时会显示缓存列表并说明原因。发布和团队共享需要 classic GitHub 令牌。
自主读取和操作需要支持 function calling 的模型。
端点必须接受来自浏览器扩展的请求（公开 API 可以，严格的内网网关可能不行）。
保存的密码静态存储时不加密。

许可证

本项目采用 PolyForm Noncommercial License 1.0.0（PolyForm 非商业许可）：个人学习、研究、实验、教学及非营利组织（慈善、教育、政府机构等，不论资金来源）可免费使用、修改和分发，但需随副本附上本许可文本与来源声明；商业使用需向作者单独获取授权。本协议为"源码可得（source-available）"许可，不属于 OSI 认证的开源协议；软件按"现状"提供，不附带任何担保，作者不对使用后果承担责任。第三方依赖仍遵循其各自的许可证；商业授权请通过仓库主页联系作者。

dcc123456/browser-copilot

实测星标增长

关于

README.zh-CN.md