BrowserSkill Rust 工作区拆解：bsk-cli 与 bsk-protocol 如何分工驱动浏览器自动化

【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill

你让 AI 去点一下登录页的按钮，它凭什么能碰到你已登录的 Chrome？BrowserSkill 给的答案是一个 Rust 工作区：bsk-cli 负责命令行与守护进程，bsk-protocol 负责消息契约，加上浏览器扩展，三者拼成一条可落地的浏览器自动化链路，让 AI Agent 直接复用你真实的登录态。

跟着一帧 JSON-RPC 跑完全程

以bsk click为例，一次点击的完整链路长这样：

bsk click (crates/bsk-cli/src/cli/interaction.rs) ↓ IPC：JSON Lines over UDS（src/ipc_client.rs） bsk daemon 的会话队列 (src/daemon/queue.rs) ↓ WebSocket :52800 (src/daemon/ws.rs) 浏览器扩展执行点击 ↑ 按 bsk-protocol 的 Frame 约定回传 ResponseFrame

链路的第一段发生在进程内：clap 把参数解析成结构体，ipc_client从~/.bsk/daemon.json找到 socket 路径，发出一行 JSON。daemon 收到后不直接转发，而是先塞进该会话专属的串行队列，再由 WS 服务推到扩展侧。扩展在页面里真正完成点击，把结果封进 ResponseFrame 原路送回。CLI 把 JSON 反序列化成 Rust 类型，渲染成终端输出。整条路上没有魔法：每一跳传输的都是同一种帧结构。

契约层优先：把 bsk-protocol 当电报格式手册读

如果把 bsk-cli 比作发报员，那 bsk-protocol 就是电报格式手册——报文长什么样、字段怎么排、哪些组合合法，全部在这里规定。这个 crate 的依赖面很小：serde、schemars、semver、thiserror，没有 tokio 也没有网络库，纯粹是类型加校验逻辑。

• src/frame.rs：三种信封。RequestFrame（id + method + params）、ResponseFrame（id + result/error 二选一）、EventFrame（单向事件）。事件种类是封闭枚举：system.heartbeat、session.user_interrupt、browser.disconnected等。响应帧的 deserializer 手写了一组规则——result 与 error 恰好出现一个，两个都出现或都缺失直接拒绝解码，从根上堵住歧义报文。
• src/method.rs：方法名枚举。每个方法是一段命名空间字符串（system.handshake、tool.tab_list），同时标注副作用等级：被动读、瞬时输入、浏览器变更、控制平面，供上层做中断与安全策略。
• src/tools/：所有tool.*的入参出参类型按功能域拆文件——interaction.rs（click/fill/hover）、navigation.rs、observation.rs、record.rs加record_v2/v3.rs（录制轨迹的三代演进）、tabs.rs，另有waits.rs、wheel.rs、window.rs等。

把 90+ 份 JSON Schema 当 API 合同读

schema/ 目录里有 111 份 JSON Schema，全部由schemars从 Rust 类型推导出来。价值在于它不依赖任何 Rust 环境：TypeScript 写的扩展、Node 侧的调试脚本，拿tool_click_params.json就能离线校验一条请求的形状。trace.json到trace_v3.json并排摆着，协议版本的演进在文件列表里一目了然。

用 dump-schema 重新生成全部合同

类型改了之后，运行cargo run -p bsk-protocol --bin dump-schema --locked即可把 schema/ 全量重刷，保证 Rust 类型与 JSON 合同始终一致。协议变更从此是一次可审计的文件 diff，而不是散落在多个 crate 里的隐式改动。

实现层：逐块拆 bsk-cli

编译出来的bsk命令就在这个 crate 里（工作区当前版本 0.3.2，edition 2024，Rust 1.85）。

• src/cli/mod.rs是子命令总入口，screenshot、navigate、click、record等 30 多个命令各占一个 .rs 文件，一命令一文件。以 src/cli/screenshot.rs 为例：clap 定义ScreenshotArgs，dispatch()先经ensure_daemon()确保守护进程在跑，再走 IPC 发出tool.screenshot请求。
• src/ipc_client.rs是 CLI 侧的 IPC 通道：Unix 走 Unix socket，Windows 走命名管道，协议是 JSON Lines；每次call新建一条连接，发一行、收一行，响应反序列化成目标类型。
• src/daemon/是长驻后台进程，mod.rs里同时拉起 WS 与 IPC 两个服务，默认 WebSocket 端口 52800（DEFAULT_WS_PORT）。子模块按职能切分：ipc.rs、ws.rs、sessions.rs、queue.rs、remote/，另有inflight.rs管在途取消、lockfile.rs管单实例、start.rs管启动与空闲回收。其中 daemon/queue.rs 为每个会话维护一条串行 mpsc 队列：tool.*请求逐个取、逐个转发，避免并发工具调用把扩展侧的会话状态搅乱。
• src/skill_install/通过include_str!把 skill/SKILL.md 打包进二进制，再按 harness 清单装进各家 AI 编程助手的技能目录，来源区分 bundled 与 custom，写入带溯源标记。
• tests/有 39 个集成测试文件：ipc_smoke.rs验证 IPC 冒烟，lockfile.rs看单实例，handshake_compat.rs锁协议兼容行为。改任何模块之前，先翻对应测试，它写明了边界行为。

动手改造：挑一条路径改起来

新增一条 bsk 子命令—— 在 src/cli/ 下新建 .rs，用 clap 定义参数结构体与dispatch()；到 src/cli/mod.rs 挂进子命令枚举；若请求类型尚不存在，再去 bsk-protocol 补方法。对照测试：tests/cli_parse.rs和tests/exit_codes.rs。

扩展一个 RPC method—— 在 bsk-protocol/src/method.rs 的Method枚举里加一条命名空间字符串并标注副作用等级；在 src/tools/ 对应文件里定义 Params/Result 两个类型；跑dump-schema刷新 JSON 合同。回归测试：tests/tools_ipc.rs、tests/tools_m9_ipc.rs。

改协议兼容检查—— 核心逻辑集中在 bsk-protocol/src/system.rs：compare_protocol比较协议版本先后，evaluate_handshake_compat输出三态判决——同 major 且双方最低兼容线都满足时放行，版本漂移记为 Skew 但允许连接，major 不符直接 Reject。改动前先读tests/handshake_compat.rs，再跑tests/ws_handshake.rs。

更完整的组件关系、远程模式与沙箱场景，见仓库内的 docs/architecture.md。

【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI + extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill