helperContext()设计哲学：为什么ego-lite浏览器自动化的辅助面是唯一事实源-育师

helperContext()设计哲学：为什么ego-lite浏览器自动化的辅助面是唯一事实源

【免费下载链接】ego-liteThe fastest browser for AI agents to run browser automation, built for sharing your logged-in browser state with your AI agents, like Codex or Claude Code, without disturbing you. Zero cost, zero config.项目地址: https://gitcode.com/GitHub_Trending/eg/ego-lite

🧭ego lite（ego-lite）是专为 AI Agent 打造的最快浏览器自动化浏览器：Agent 在独立的 Space 里运行浏览器任务，直接复用你已登录的真实浏览器状态，全程不打扰你自己浏览，零成本、零配置。而在它的开源核心ego-browser中，有一个不起眼的函数撑起了整个 Agent 可调用的能力面——helperContext()。本文带你读懂它的设计哲学：为什么"唯一事实源"是 ego-lite 又快又省的秘密所在。

一、先认识 ego lite：你和 AI Agent 共用一个浏览器

传统浏览器自动化框架（如 browser-use）需要额外驱动一个独立浏览器，登录态难以继承，人和 Agent 还会抢标签页。ego lite 反过来设计：同一个浏览器，两套并行世界——你在前台浏览，Agent 在后台 Space 中干活，互不干扰。

任何 Agent（Claude Code、Codex、Cursor 或自研）都通过ego-browser接入：Agent 写一段 JavaScript，调用页面上注入的一组工具（snapshot、fill、click、wait、navigate、capture），一次性执行完成。

那么问题来了：这组"注入的工具"在哪里定义？答案是 helpers.ts 里的helperContext()。

二、两条入口路径，却只有一个"事实源"

ego-browser有两个启动路径（见 index.ts）：

CLI 路径：Agent 把 JavaScript 从 stdin 喂进来，由runMain()执行；
SDK 路径：ego lite 应用把它内嵌进浏览器运行时，调用installEgoSdk()。

两条路径如果各自维护一份"能调什么函数"的清单，很快会漂移：CLI 有help()而 SDK 没有、这个路径能click那个路径却不行……对新手用户来说，文档说有的功能换个入口就消失，这是最糟糕的体验。

ego-lite 的解法在 run.ts 中写得很直白——注释原话就是"Single source of truth for the agent-facing surface"（面向 Agent 的能力面的唯一事实源）。无论哪条路径，最终都调用同一个helperContext()来构造注入对象，从根上杜绝漂移。

三、统一的能力面：五大门面 + 一个 help()

helperContext()并不是一堆函数的平铺，而是组织成 5 个清晰的"门面"（facade）：

门面	职责
`page`	Playwright 风格的页面操作：goto、locator、getByText、等待、截图、录屏、键盘与鼠标
`browser`	标签页管理：列表、切换、打开/关闭
`taskSpaces`	任务空间：新建、接管、交接、完成——人机并行不抢标签页的关键
`site`	站点经验（learnings）：复用已沉淀的站点工具与工作流
`fetch`	网络请求：区分 Node 端与浏览器端发起

外加一个内置的help()：它不是死文档，而是从这同一组函数本身提取的文档。help-runtime.ts在构建时解析函数上的 JSDoc 并注入运行时（见 help-runtime.ts），所以JSDoc 就是用户可见文档——Agent 调help("page")拿到的说明，永远和实际能调用的函数一一对应，不可能出现"文档写了、功能没有"。

四、胶囊设计：只给该给的，藏好内部实现

唯一事实源还意味着精确控制暴露边界。taskspace-e2e.test.mjs 中有一条专门验证这一点：在 Agent 脚本作用域里，helperContext、loadAgentHelpers等内部函数是undefined，旧的扁平全局函数（如click）也已不可见——Agent 只能看到 5 个门面和help()。

这就像胶囊的胶囊壳：外面只留干净的接口，内部实现怎么重构都不影响 Agent 的写法。行为测试同样如此，helpers.test.mjs 直接断言helperContext()暴露的完整门面结构，改错一个键名就会立刻被捕获。

五、可插拔扩展：agent_helpers.js 的注入位

helperContext(extra)接收一个extra参数，而 run.ts 会把工作区中的agent_helpers.js（由 helpers.ts 的loadAgentHelpers()加载）合并进来。

这意味着：你给自己的 Agent 写的私有小工具，和官方能力走的是同一条注入通道——同样出现在脚本作用域里、同样被help()覆盖，而不是另开一个旁路。扩展即事实源的一部分，而非事实源之外的影子系统。

六、给贡献者的纪律：新 Helper 的三道关卡

项目指南 AGENTS.md 为这条哲学立了规矩：任何新的公开 Helper必须经过helperContext()，必须写 JSDoc（因为它直接喂给help()），并且保持 SKILL.md 同步。三道关卡保证了"能调用的、有文档的、写进技能指南的"三者永远一致——这是唯一事实源在维护流程上的延伸。