《WorkBuddy Skills 实战》第20招 五分钟跑通第一条链
## 01、痛点 我是老李。这几天同事群里高频出现同一类问题:给 WorkBuddy 装了一堆能力扩展,最后却连一个网页都没跑起来。 有个做交付的兄弟,一下午装了浏览器自动化、缺陷诊断、日志、CI、告警、知识库等 15 个扩展。启动工作台后,上下文又长又乱,还报权限错误。他发来的日志前几行是 Playwright 初始化失败,后面却跟着十几条能力包版本冲突。真正的错误被噪音淹没了。 这种事并不少见。很多人遇到工具生态,第一反应不是跑通一件事,而是先集齐所有能力。结果第一个网页没打开,第二个、第三个扩展已经抢着报错。 这里有两个更隐蔽的坑。 第一,清单式安装。装得越全,能力越强的错觉,会让新手在还没验证核心链路时,就把复杂度拉满。反馈周期一长,人就容易怀疑工具,而不是怀疑安装顺序。 第二,安装器命令和普通 Shell 命令被混在一起。比如文档里出现 `$toolkit-installer`,不少读者会直接复制到终端敲。其实这个带美元符号的字符串是变量引用,不是系统里现成的可执行文件。把变量当命令用,当然会报 `command not found`。 这两个坑叠加,把十分钟能验证的问题拖成半天。所以我们要换一种打法:不要一次装 15 个,先拿到第一个闭环价值。 ## 02、是什么 WorkBuddy 的能力包,不是系统可执行程序。它更像一个运行时挂载单元,里面通常包含描述文件、脚本、配置和依赖声明。安装器负责把这个单元放进扩展目录,并在当前工作台环境完成注册。安装动作要在 WorkBuddy 的上下文里完成,而不是直接在终端敲一个孤立命令。 可以把它类比成手机应用商店里的某个自动化配置,而不是系统自带设置。你要安装,必须经过应用商店或管理入口,而不是自己直接去改底层驱动。这个类比不一定完全准确,但能帮助新手记住一个关键点:安装能力包和运行系统命令是两条路。 Playwright 是浏览器自动化运行时。它能启动真实浏览器,打开网页、读取页面结构、点击按钮、输入文本、截图,甚至等待某个元素出现。它和普通脚本最大的区别是,它操作的是真实页面,不是模拟 DOM 或静态抓取。很多动态渲染、跳转、登录后的状态变化,只有真实浏览器才能给出可信结果。 WorkBuddy 加 Playwright,解决的是一个非常具体的场景:你告诉它目标,它驱动真实浏览器完成操作,并把可验证的结果带回来。比如读取登录按钮是否存在、点击后 URL 有没有变化、表格里有没有出现新数据。这个组合的核心价值不是聊天,而是闭环。所谓闭环,就是指令发出去以后,能返回一个你肉眼可确认的结果。 ## 03、为什么 为什么现在要讲这个?因为工具生态越来越丰富,反而让很多人掉进完整性陷阱。好像不装完全部能力,就不好意思开工。 可学习工具的进度,从来不看你装了多少包,而看你多久拿到第一个可验证结果。五分钟跑通一条真实链路,比读完一整页能力清单重要得多。 从认知负荷看,一次装 15 个能力扩展,至少带来三层负担。 第一,依赖冲突。不同能力包可能依赖不同版本的浏览器或运行时。一次装太多,排错难度指数上升。你可能不知道是 A 包和 B 包冲突,还是环境变量错了。 第二,命令入口混乱。有些能力通过 WorkBuddy 调度,有些需要外部配置,新手很容易把不同的调用方式搞混。尤其当文档里同时出现裸命令和变量引用时,更容易复制错。 第三,反馈不聚焦。一个包失败会污染其他包的判断,你不知道是基础环境坏了,还是某个扩展本身有问题。错误信息越多,真正的原因反而越难找。 反过来,先装一个。链路短,出问题就那两三个变量。搞定一个,再装第二个,每一步都有真实任务驱动。真实工作流里,今天最紧急的问题大概率不是我要一个全能助手,而是某个具体任务很痛:自动打开后台页面读数据、自动点击导出按钮、自动做一次冒烟回归。这类任务用 Playwright 跑通,立刻就有生产力。 ## 04、架构 为了把这个问题讲清楚,可以把 WorkBuddy 与浏览器自动化能力分成四层。 第一层,入口层。WorkBuddy 是主控入口,负责理解目标、调度已注册能力、判断依赖是否齐全。它知道当前环境里哪些能力可用,哪些缺失。 第二层,能力管理层。安装器通常由 WorkBuddy 内部调用,可能表现为 `workbuddy capability install playwright`。如果文档里写的是 `$toolkit-installer install playwright`,它的意思是:`$toolkit-installer` 是一个变量,指向能力包安装器路径。它不是系统 PATH 里的可执行文件。不要把它当成 `ls`、`cat`、`npm` 那样的命令。 第三层,运行时层。Playwright 启动真实浏览器进程,通过进程通信或调试协议控制页面。WorkBuddy 把抽象目标翻译成可执行步骤,比如读取标题、获取文本、点击元素、等待跳转。 第四层,结果层。截图、页面文本、点击后的状态变化、结构化日志,返回给用户确认。闭环价值来自这一层:你看到了真实结果,而不是只听一句我成功了。 这种分层的好处是排错时能快速定位。包装不上看管理层,驱动不了看运行时层,点击没反应看页面选择器或结果层。不同层的问题不要混着查。举几个典型错误:如果提示变量未定义,多半是把变量引用当成命令了;如果提示浏览器可执行文件缺失,多半是 Playwright 的浏览器运行时没装好;如果页面打开了但点击超时,多半是元素选择器变了。 ## 05、实战 下面按最小闭环操作。目标不是展示复杂功能,而是让一个真实网页被打开、被读取、被操作。 第 0 步,确认工作台入口。假设你的入口命令是 `workbuddy`。先执行: ``` workbuddy doctor ``` 查看运行环境是否正常。再执行: ``` workbuddy capability list ``` 看当前可用的能力包列表。注意,这些命令都要通过 WorkBuddy 入口执行,不要去系统终端找 `capability` 这个独立程序。 第 1 步,安装 Playwright 能力。正确做法是让 WorkBuddy 自己调用安装器: ``` workbuddy capability install playwright ``` 如果资料里写的是 `$toolkit-installer install playwright`,请一定看清:`$toolkit-installer` 是变量,不是命令。你需要先在 WorkBuddy 或 Shell 初始化脚本里给它赋值,或者直接用 WorkBuddy 提供的封装命令。不要直接复制带美元符号的字符串到终端,否则会报 `command not found`。 第 2 步,运行第一个网页任务。以示例站点为例: ``` workbuddy run playwright --url https://example.com --action '读取页面标题,然后点击 login' ``` 等待输出。如果链路正常,你会看到浏览器启动、页面打开、返回标题文本,以及点击后的 URL 或页面状态变化。这一步成功,就完成了一个最小闭环。 第 3 步,换成你自己的业务页面。比如内部后台的列表页,读取表格前 10 行,或者点击导出按钮。建议先选不需要登录的页面,减少变量。如果必须登录,优先用已登录的浏览器上下文或测试账号,不要一上来处理复杂认证。 如果安装完发现浏览器没有启动,先看 `workbuddy doctor` 里的浏览器运行时是否安装;如果提示变量未定义,检查 Shell 初始化脚本;如果页面打开但点击失败,先确认元素选择器是否变化。一步步缩小范围,不要急着重装全部环境。 进阶顺序要收敛。第二个装 `diagnosing-bugs`,用来把失败日志、报错堆栈、环境信息结构化,方便后续定位问题。第三个再按自己的工作流选择 CI、Sentry、内容管理或知识类能力包。原则是:每加一个包,都要有当前任务需要,而不是因为清单上看着顺眼。 ## 06、洞见 学习新工具最好的方式,不是先读完整清单,而是五分钟做出一个可验证结果。 工具的价值必须在真实反馈中显现。清单再长,如果不产生可感知的变化,心智模型也建立不起来。你记住的往往不是文档里的功能列表,而是第一次看到浏览器自动打开并完成点击的那一瞬间。 可验证结果有几个特征:时间短、命令少、输出可见。例如打开网页并读取标题,十秒内就能判断成功与否。被验证过的链路会变成锚点。后面再装诊断、告警、CI 等能力时,你有了对照:是新增包坏了,还是基础链路坏了。 为什么五分钟比一小时更有效?因为短链路帮助建立最小的心理表征。你能记住一条从安装到运行到结果的路,而不是只记得一堆零散名词。 另一个洞见是:工作流不是装出来的,是长出来的。先让一个能力包真正解决今天的问题,用顺了,再让它长成自己的 WorkBuddy 工作流。每一步增长都有真实任务驱动,而不是为了完整性。 ## 07、行动 如果只做一件事,就做这句:先装一个真正解决今天问题的能力包,用顺了,再让它长成自己的 WorkBuddy 工作流。 具体可以这样开始。 第一,把今天最想自动化的网页任务写下来,越具体越好。不要写我要自动化网页,而是写我要打开后台订单页,读取前 10 条订单号。 第二,只挑一个能力包解决它,不要顺手装别的。先装浏览器自动化,跑通再说。 第三,跑通最小闭环,记录一条命令和一次输出结果。最好截图或保存日志,作为基线。 第四,明天再考虑加第二个包,比如缺陷诊断或错误监控。一周节奏可以是:第一天跑通网页操作,第二天加诊断能力,第三天接一个真实任务,周末再扩展。 不要一次装 15 个,不要先读完整清单,也不要把带美元符号的变量当成系统命令。 ## 08、小结 这篇文章不是劝你少用工具,而是劝你先拿到结果。WorkBuddy 加 Playwright 的价值,在于让网页操作从我觉得可以变成我看到了。 最小闭环、真实反馈、按需扩展,这三件事比多装几个包重要得多。先把一个能力用顺,它自然会成为后续工作流的地基。工具永远是为解决今天的问题服务,不是用来集邮。 ## 09、链接与概念说明 `WorkBuddy`:本文默认的工作台入口,能力包安装和运行都要在它的上下文中执行。 `Playwright`:浏览器自动化运行时,支持真实浏览器操作、读取页面、截图和脚本化交互。 能力包:本文用来指代那些可安装扩展,本质是描述文件、脚本、配置和依赖声明的组合。 `$toolkit-installer`:变量引用,不是系统可执行程序。它在配置或文档里出现时,不要直接当成命令敲。 `workbuddy capability install`:安装能力包的示例入口,实际命令以你使用的 WorkBuddy 版本为准。 `diagnosing-bugs`:可用于诊断缺陷的扩展,建议在基础链路跑通后第二个安装。 `CI`:持续集成,适合在基础链路稳定后接入。 `Sentry`:错误监控服务,适合与诊断能力配合使用。