自动化工具集体失灵之后：一次协议版本不匹配的排查复盘

一、现象：所有"写"操作突然全部被拒绝

故事从一次例行任务开始。一个已经连续跑了十几天的浏览器自动化脚本，某天早上突然宣布罢工：点击、输入、跳转、刷新——所有会改变页面状态的动作，全部返回同一条错误：

  This action requires the context returned by the latest cooperate sync

而"读"类动作——观察页面结构、截图——依然正常。这个特征很关键：它不是浏览器没起来，也不是页面打不开，而是**写权限这一层被单独掐断了**。

二、第一轮排查：把疑点逐个排掉

面对这类"部分失效"的故障，最忌讳的是直接推倒重来。先按成本从低到高排列假设：

1. 会话失效？新建一个会话，错误照旧。
2. 标签页被用户抢走？切到另一个标签，错误照旧。
3. 页面没加载完？等待网络空闲再试，错误照旧。
4. 插件崩了？重启宿主应用，错误照旧。

四条排完，问题范围就从"偶发状态异常"缩小到"协议层不兼容"。这时候换思路：不再从上层猜，而是直接找工具链最底层的那个可执行文件。

三、找到根因：协议版本 1.7 与 1.8

插件在界面上只把最外层的错误抛出来，真正的判断发生在一个独立的命令行工具里。把它单独调起来，让它自己解释：

  bsk cooperate sync --session <SID> --policy auto --json

返回的第一句话就是答案：

  unsupported: extension protocol 1.7, target control requires 1.8

浏览器扩展报告的协议版本是 1.7，而这个命令行的 target 控制层要求 1.8。命令行的提示很克制，只在 hint 里写了一句：旧扩展必须显式使用 --policy strict。

也就是说，插件默认走 target 策略，而目标扩展只支持更保守的 strict 策略。两边谁都没错，只是没人把版本对齐——这种故障在界面层看起来就是"什么都没说清楚"。

四、绕过门禁：strict 策略 + 一次性上下文

改成 strict 之后，同步立刻成功，返回结构里包含三样东西：

  context_id   —— 本次授权的凭据
  observation  —— 当前页面的无障碍树与 @eN 引用
  tab_id       —— 操作的标签页

这里有一条必须记住的规则：**一个 context 只授权一个动作**。点击一次，context 就作废，下一次操作必须重新 sync。这不是冗余设计，而是把"授权-执行"绑成原子单元，避免一个凭据被无限复用。

理解了这条规则，整个调用序列就变成固定节奏：

  sync → click → sync → fill → sync → navigate → ...

看起来笨，但极其可靠：每一步都有新的页面快照，引用永远是最新的，也不会因为页面在两次操作之间自己重渲染而点错元素。

五、踩到的第二个坑：命令行参数里的 JSON

有了正确策略，新的问题来了。工具提供了 step 子命令，可以"动作 + 同步"一步完成，参数是一个 JSON 对象：

  bsk step --action click --params {"ref":"@e11"}

在 Windows PowerShell 5.1 里调用外部程序时，参数里的双引号会被吞掉，到达程序时变成 {ref:@e11}，于是解析器报：key must be a string at line 1 column 2。

这不是工具的问题，是 shell 传参的老毛病。两个解法：

一是改用不需要 JSON 的独立子命令（click / fill / navigate 都有对应的 --ref、--selector、--value、位置参数），把 JSON 彻底绕开；

二是把参数写入文件，由脚本读入后用 .NET 的 ProcessStartInfo 构造参数串，自己处理引号与反斜杠转义——这样 Unicode 也能安全传递。

两害相权，日常操作选第一种，需要传长文本时选第二种。

六、经验沉淀

这次故障从发现到完全恢复，真正有效的动作只有三个：找到底层可执行文件、让它自己报版本、按提示切换策略。前面四个假设花掉的时间，几乎都是因为"界面只说了一句话"。

所以留下三条结论：

第一，报错信息里出现 "requires ... returned by ..." 这类措辞时，优先去找提供方，而不是怀疑使用者。

第二，任何分层的工具链，都要知道最底层那个可执行文件在哪。上层封装的便利性越高，排障时越需要下沉。

第三，协议版本号不该只出现在日志里。插件启动时把扩展版本和自身期望版本各打一行，能省掉后面所有的猜测。

工具链的可靠性，从来不取决于它平时有多顺，而取决于它出错时能不能把原因说清楚。