OC
OpenClaw 中文解释版

给五岁小朋友也能看懂的说明书

简要总结

Browser Evaluate CDP Refactor

这页文档讲的是怎么让电脑里一个叫“浏览器”的程序,在帮我们运行一些特殊指令(JavaScript)的时候,变得更安全、更听话。以前,如果这个指令卡住了,整个浏览器页面都会跟着卡住,不能做别的事情。现在,大人们想了一个新办法,让这个指令在一个单独的小房间里运行,这样就算它卡住了,也不会影响我们点按钮、打字这些正常的操作。这页就是告诉大家这个新办法是怎么做的。

五岁小孩版解释

想象一下,你让浏览器帮你运行一个叫 act:evaluate 的指令,就像让它去一个房间里完成一个任务。以前,这个房间只有一个门,所有任务都排着队从这个门进出。如果一个任务在里面玩很久不出来(卡住了),后面的任务就都进不去,整个页面看起来就像“睡着”了。

大人们现在要修一个新门,专门给 act:evaluate 任务用。这样,就算它卡住了,其他任务(比如点击、打字)还是可以从原来的门正常进出,不会受影响。这个新门,我们叫它“CDP路径”。

为了让这个新办法成功,大人们需要做好几件事:

  1. 给任务一个“沙漏”:每次派任务时,都要告诉它“你最多可以玩多久”,这叫 timeoutMs。这个时间限制会像沙漏一样,从任务开始一直跟着它,不管它走到哪里(比如通过网页请求,或者直接在电脑里运行),大家用的都是同一个沙漏。时间一到,任务就必须停下来。
  2. 建一个新房间(CDP路径):大人们会写一个新的小工具(比如叫 cdp-evaluate.ts)。这个工具会自己开一条秘密通道(WebSocket连接)直接和浏览器对话,不和其他任务挤在一起。这样,act:evaluate 任务就可以在这个新房间里安全地运行了。
  3. 教新房间认识“小积木”:有时候,我们的任务是想对页面上的某个东西(比如一个按钮)进行操作。这个东西我们用一个叫 ref 的标签来标记。以前,只有旧房间认识 ref。现在,大人们要在 ref 这个标签里,偷偷加一个只有新房间才认识的密码,叫做 backendDOMNodeId。这样,当任务带着 ref 来时,新房间如果能看懂密码,就用新房间来执行;如果看不懂,就还是让旧房间(Playwright)来执行,这样就不会出错。
  4. 永远留一条后路:就算有了新房间,万一还是出问题了呢?所以,以前那个在任务卡住时强行叫停的“安全网”还会保留着。如果新房间用不了,或者遇到其他奇怪的情况,我们还能用这个老办法来恢复,保证浏览器不会真的“死掉”。

大人们会按照一个清单来一步步完成这个改造:

  • 先做好“沙漏”工具,让所有地方都用上统一的时间限制。
  • 然后建好新房间(CDP路径)的工具。
  • 接着,在给页面拍照(生成快照)的时候,就悄悄把那个新密码 backendDOMNodeId 加到 ref 标签里去。
  • 最后,让 act:evaluate 指令学会:有密码就用新房间,没密码就用旧房间。

这里要小心几件事哦:

  • ref 找对应的密码 backendDOMNodeId 可能不会每次都成功,找不到也没关系,我们用旧房间就好了。
  • 在新房间里强行停止一个任务(用 Runtime.terminateExecution),可能会让那个任务正在做的事情突然中断,就像故事讲到一半被合上书一样。
  • 用新办法可能会让电脑多花一点点力气,所以大人们会想办法,只在需要的时候才去问浏览器要密码,并且用完了就赶紧关掉秘密通道。

总之,这个计划就是为了让 act:evaluate 指令变得更乖,即使它自己贪玩卡住了,也不会耽误我们做其他更重要的事情。