hooosberg/AgentLimb
hooosberg/AgentLimb has 78 GitHub stars and 20 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-18 11:52 UTC. Last push 2026-11-15.
实测星标增长
- 24小时
- +1
- 7天
- 正在收集历史
- 15天
- 正在收集历史
- 1个月
- 正在收集历史
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Let any MCP AI agent drive your real Chrome. Copy one prompt to pair — no confirmation page, no pairing code. 100% local.
人工智能README.zh-CN.md
原文AgentLimb
English · 简体中文
官网 / 产品页(落地页)→ https://hooosberg.com/apps/agentlimb/ · 下载最新版 · 旧版官网
当前源码版本:0.8.1 / l21(变更记录见 CHANGELOG.md)。
通用浏览器控制插件:给任意支持 MCP 的智能体软件装上「手」,让它能控制你的 Chrome。
复制提示词即完成首次授权,之后可自动重连。 智能体软件里的 MCP 启用/信任仍由该软件处理;复制打开的 30 分钟窗口内,第一个连上来的 AI 自动受信,全程没有确认页也没有配对码。侧边栏没连接时提供接入提示,连接后变成聊天窗。 侧边栏开不开,AI 都能干活——它会在自己的后台标签页里操作,不打扰你当前看的页面。
快速开始
# 1. 检查 Node.js >=18,然后安装本地 MCP 宿主并生成配置 JSON
node --version
bash scripts/install.sh --client-name "WorkBuddy" --client-kind "workbuddy"
# Windows: powershell -ExecutionPolicy Bypass -File scripts/install.ps1 --client-name WorkBuddy --client-kind workbuddy
# 2. Chrome 加载插件
# chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选择本目录
# Windows:本目录必须放在纯英文路径(如 C:\AgentLimb)
# 路径含中文会加载失败,详见下方说明
# 3. 点击插件侧栏的「复制连接提示词」,把提示词交给目标智能体
# 复制本身就授权了这次接入(30 分钟窗口),提示词里没有任何码要填进配置
# 在软件要求时启用/信任 MCP,并按需重载
# 4. 从当前智能体会话调用 AgentLimb ping 与 tabs_context 验收;不会出现任何确认页
安装器只负责安装宿主文件和打印 JSON,不会写入任何智能体软件配置。复制提示词打开的接入窗口 30 分钟有效、只授权一个 AI;窗口过期就再点一次复制,不需要改配置或重启。客户端配置格式、MCP 启用/信任入口由各软件决定;不要把通用 JSON 示例当成已启用。
Windows 用户注意:插件目录必须解压到纯英文路径(如
C:\AgentLimb)。 路径含非 ASCII 字符——最常见的是中文用户名,如C:\Users\张三\Desktop——会让 Chrome 拒绝加载,报Could not load javascript 'kernel/control/content/a11y-tree.js' for script.含空格不影响;macOS / Linux 不受此限制。已在真实 Windows(Edge 155 / Chrome 156)实测确认。
本地调试(不装 Claude Code 也能跑):
node bin/agentlimb.mjs mcp # stdio MCP;收到 initialize 后启动桥接
node bin/agentlimb.mjs status # 探测桥接是否在线
npm test # 协议端到端测试(含模拟扩展)
连不上时按顺序排查
每一步只排除一个阶段,前一阶段通过不代表后一阶段可用。
| 现象 | 含义 | 怎么办 |
|---|---|---|
Windows 上扩展加载失败,报 Could not load javascript … |
插件目录路径含中文(非 ASCII 字符) | 把目录挪到纯英文路径(如 C:\AgentLimb)再加载;含空格不影响 |
| 工具调用返回「未授权」 | 30 分钟接入窗口过期,或已被另一个 AI 用掉 | 再点一次「复制连接提示词」,不用改配置或重启 |
| 软件里能看到 AgentLimb,但工具没反应 | 配置合并了,但该软件没启用/信任 MCP,或进程没起来 | 在软件里启用并信任 MCP,然后重启它的 MCP 进程 |
| 完全没有反应 | 宿主可能不在配置指向的位置 | node bin/agentlimb.mjs status,并确认 ~/.agentlimb/host/mcp-server.mjs 存在 |
| 第二个 AI 接不过来 | 第一个 AI 忙时,controller 独占浏览器任务锁 | 等当前任务结束;忙碌时拒绝强切是设计如此 |
| 首次连接要等一会 | Service Worker 当时在休眠 | 打开侧栏即可唤醒,否则最长约 1 分钟自动连上 |
只有你真正要用的那个会话里 ping 与 tabs_context 成功,才算连接可用。端口可达、信任文件存在、别的客户端连上,都不能替代这一步。
架构
┌─────────────┐ stdio MCP ┌──────────────────────┐ SSE(推送) ┌─────────────────────┐
│ 智能体软件 │ ◄──────────► │ host/mcp-server.mjs │ ◄───────── │ 扩展 Service Worker │
│ (任意客户端) │ JSON-RPC │ host/bridge-server │ POST(回传) │ debugger 持久会话 │
└─────────────┘ └──────────────────────┘ │ + content scripts │
127.0.0.1:8765-8780(最多16个宿主) └─────────────────────┘
三个角色,零依赖(纯 Node 内置模块 + 原生 JS,无 npm 包):
| 层 | 文件 | 职责 |
|---|---|---|
| 扩展后台 | kernel/control/background/ |
桥接客户端(SSE/POST)、CDP debugger 管理、工具路由 |
| 页面脚本 | kernel/control/content/ |
a11y 树生成(document_start 常驻)、控制指示器 |
| 侧栏 | ui/sidepanel/ |
连接提示词、按 AI 隔离的聊天、客户端管理、设置(无确认页) |
| 本地宿主 | host/ bin/ |
MCP stdio 服务器 + 本地 HTTP/SSE 桥接 |
| 共享 | kernel/shared/constants.js kernel/control/host/tools.js kernel/prompt/ |
协议常量、工具目录(双端同源)、提示词生成 |
安装、客户端信任与浏览器授权是不同阶段
安装器部署 ~/.agentlimb 并打印 mcpServers.agentlimb 配置。用户把它合并到目标软件的真实配置后,还需按软件要求启用/信任 MCP。侧栏的「复制连接提示词」同时完成授权:扩展打开一个 30 分钟窗口,窗口内第一个连上来的未知 AI 自动受信,没有确认页、没有配对码。窗口过期或已被用掉时,工具调用会立刻返回「未授权」,让用户再点一次复制即可,不用改配置或重启。只有当前目标会话调用 ping 和 tabs_context 成功,才证明连接可用。
宿主为客户端名称与类型组合建立稳定身份文件;旧版共享 client-id.json 不会继承信任。同身份已存信任可自动重连,且不会抢当前聊天窗;新身份需要一次接入窗口。运行时旧目录、可达端口、信任文件或其他客户端成功,都不能单独证明当前客户端已经连接。
扩展最多同时连接六个 MCP 宿主并保留各自 trust;connectedClientId 标记唯一 controller。已信任客户端握手不自动抢控制,显式切换仅在任务空闲时生效;忙碌时拒绝强切。其他客户端非 ping 工具按宿主 deadline 排队,过期不执行。
交互原则
- 侧边栏与控制彻底解耦:工具调用走 SW ↔ 桥接,与侧栏是否打开无关。
- 未连接:侧栏提供复制提示词;顶部还可打开设置。
- 已连接:侧栏就是和当前 controller 的聊天窗。顶栏保留复制提示词和设置入口,并显示当前 AI 与已配对数量。每条消息自动带上 当前标签的截图 + 标题/URL + 正文摘录 + 可交互元素 ref,所以「这页讲什么」「帮我点这个」 都不需要先截图或先报标签。Enter 发送、Shift+Enter 换行。
- AI 的回复回到同一个窗口(
say工具),操作过程折叠成一行「执行了 N 步操作」, 点开才展开——聊天流不被日志淹没。 - 页面内的控制反馈:辉光边框 + 幽灵光标,用户在哪个标签都能看到 AI 在动哪个标签。
- 多客户端信任独立保留:临时断线和 MCP 退出只标记离线;设置里的移除仅撤销所选客户端信任。
- 单 controller 串行执行:另一个已信任客户端不会因启动或握手自动抢控制。用户可在空闲时切换;忙碌时不强切。新配对客户端等待当前任务结束后接管。
ping只检查,不抢控制。
效率设计(对照参考实现的关键优化)
旧版(已归档的 0.2 时代代码)的控制链路是 HTTP 轮询,每一跳都有损耗。本版逐项修正:
| # | 旧版问题 | 本版方案 |
|---|---|---|
| 1 | SW 每 300ms 轮询桥接队列,加 50ms 忙轮询;SW 挂起靠 alarm 重启 relay | SSE 长连接推送,host→ext 零延迟;POST 回传;alarm 只做兜底唤醒 |
| 2 | 每个动作 debugger.attach + detach(每次 10–50ms,且和 DevTools 抢锁) |
按标签持久 attach,in-flight 去重,仅在被 Chrome 踢掉时重连 |
| 3 | 内容脚本按需注入,每次快照都问一遍 | manifest document_start 全帧常驻 a11y 脚本,ref 映射用 WeakMap 缓存 |
| 4 | 只能操作前台标签 | Emulation.setFocusEmulationEnabled 焦点模拟 + 自动静音,后台标签可操控,不抢用户焦点 |
| 5 | 截图固定 PNG,动辄超限 | JPEG 自适应质量(75→10 降级),base64 预算 ~1.2MB |
| 6 | 一步一个工具调用,来回 RTT 叠加 | browser_batch 一次提交最多 20 个动作 |
| 7 | task_plan / task_step_done / task_complete / task_fail 四个工具 + 侧栏进度渲染纯开销 | 整个进度机制移除(14 个浏览器工具,另有本地 say 与 ping) |
| 8 | muscle 记忆三件套常驻工具列表 | 本版移除 |
其他细节:CDP 命令全部带超时;console/network 在持久会话上常驻捕获(环形缓冲 200 条); 密码/敏感字段在 a11y 树里直接脱敏;同源 iframe 与 shadow DOM 可走入树并带坐标偏移。
工具清单(16 个,含本地 say 与连通检查 ping)
tabs_context tab_new tab_close tab_activate read_page find computer
form_input navigate javascript_eval wait read_console_messages
read_network_requests browser_batch say ping
目录定义在 kernel/control/host/tools.js,扩展和 MCP 宿主共用同一份——改一处,两端同步。
多浏览器 / 多账号路由(Multi-browser routing)
80% 的单浏览器用户完全零感知;当你同时打开 2 个及以上 Chrome 账号配置文件(均安装 AgentLimb,例如多账号运营场景)时,无需修改 MCP 配置即可同时或分别操控多个浏览器:
- 自动识别账号 + 侧栏一键复制与改名:每个 Chrome 配置文件自动生成持久标识(
Profile-xxxxxx),并尝试读取当前登录的 Google 账号邮箱作为默认名称。侧栏底部常驻极简「当前浏览器」标识条,点击即可一键复制标识发给 AI,点击「改名」(或进入「设置 → 高级」)可自定义简短备注名(如work、personal),保存后实时同步给宿主。 - 工具层可选
browser参数:全部 16 个浏览器工具(含navigate、tabs_context、computer、say、ping等)均支持传入可选参数browser(支持精确 ID、精确名称或无歧义子串匹配,如"work"自动匹配"[email protected]"),可并行或顺序驱动不同浏览器。 - 双通道自动提示与消歧:当同时有 2 个及以上浏览器在线时,工具返回结果会自动注入
MULTI-BROWSER (auto)提示,列出所有在线浏览器的名称与 ID;若你的指令没有指明操作哪个浏览器,AI 会先向你确认目标浏览器再执行操作。
目录
manifest.json MV3(debugger / sidePanel / tabGroups / alarms)
kernel/shared/constants.js 协议常量、SSE 帧类型、storage keys
kernel/control/host/tools.js 工具目录(唯一事实源)
kernel/control/background/
service-worker.js 入口:装配 + 消息路由 + alarm 保活
bridge-client.js 端口发现、SSE、配对管理、user_message 队列
debugger.js 持久 attach / 焦点模拟 / 自适应截图 / 事件捕获
router.js 14 个浏览器工具的执行器
kernel/control/content/
a11y-tree.js document_start 全帧注入:ref 映射 + 可访问性树
indicator.js 辉光边框 / 幽灵光标 / 停止按钮
kernel/prompt/build-prompt.js 侧栏复制的连接提示词(中英)
ui/sidepanel/ 连接引导、当前 AI 聊天和多客户端设置
host/bridge-server.mjs HTTP+SSE 桥接、信任注册表、tool_call 关联
host/mcp-server.mjs stdio MCP ↔ 桥接
bin/agentlimb.mjs CLI:install / config / doctor / mcp / status / pair-status / uninstall
host/install.mjs 共享安装逻辑与 MCP JSON 配置生成
host/diagnostics.mjs 只读连接阶段诊断
scripts/install.sh|ps1 Node 版本检查后委托 CLI 安装
tests/ Node 原生 test runner,含端到端协议测试
验收边界
npm test是自动化协议和模块测试;node scripts/live-test.mjs使用独立临时 HOME、Chrome profile、扩展副本及端口进行浏览器/MCP 集成测试,并清理本轮临时数据,不触碰日常~/.agentlimb安装。- 此前的 live 与跨平台测试报告属于历史基线,不代表当前源码版本的验收结果。
- 真实智能体客户端中的配置加载/信任,以及指定模型和猴子测试仍需独立验收;没有观测证据时不宣称通过。
已知边界
- 同时最多发现
BRIDGE_PORTS定义的候选 MCP 宿主(8765~8780,防 Winsock 端口枯竭);一个 controller 独占当前浏览器任务锁。不同 AI 的信任、聊天记录与草稿隔离。 - 侧栏聊天是「留言」语义:消息随 Agent 下一次工具结果送达(Agent 空闲时不会主动推送)。
javascript_eval走 CDP,对 CSP 严格的页面仍可执行(debugger 权限)。- 首次连接依赖 SW 被唤醒:装好后 Chrome 运行时 SW 基本常驻;若遇休眠,最长约 1 分钟内自动连上(打开侧栏可立即触发)。
与旧版的关系
本仓库 main 分支就是当前维护线(即此工作树的内容)。0.2 时代的旧版(cowork_local)
已归档到分支 archive/cowork-local,
不再更新;旧版保留任务进度机制、HTTP 轮询桥接、
12 语言 i18n 与 agentlimb.com 官网。
链接
| 官网 / 产品页(落地页) | https://hooosberg.com/apps/agentlimb/ |
| GitHub | https://github.com/hooosberg/AgentLimb |
| 旧版官网(0.2 时代,含教程 / 工具目录 / 新闻) | https://agentlimb.com/ |
觉得 AgentLimb 好用,就请去 GitHub 点个 ⭐ Star——这是对独立开发最大的鼓励, 也决定这个项目会不会继续更新:https://github.com/hooosberg/AgentLimb