上个月我把一个自动填表脚本重构到 Superpowers SDK 上，同一套功能代码量少了将近三分之二，关键是原来写死的页面选择器全都不用了——AI 直接理解"这个报价单页面的表格我需要提取"，然后把结构化结果吐出来。今天把我从安装到落地的完整过程写出来，包括我踩过的几个大坑。

如果你正在做 Chrome 扩展、想做 AI 自动化、或者想给自己的工具加一个能"看懂页面"的智能层，这篇应该能帮你省下不少时间。Superpowers 是一个面向浏览器扩展的 AI Agent 开发框架，它把模型调用、页面操作、结构化输出、记忆存储这些都封装成了可插拔模块，让你不用从零造轮子。

1. 为什么我盯上了 Superpowers

先说痛。以前做浏览器扩展里的 AI 功能，最烦的不是模型调用，而是把模型输出和浏览器操作粘起来的那些胶水代码。你想要的效果是："把这些列表数据抓下来存到表格里"，实际干的事却是一大堆 DOM 解析、正则匹配、字段裁剪、异常兜底。

1.1 传统方案的三座大山

第一座是 DOM 操作的地狱。我给你举个具体例子，我当时想抓一个后台系统的报价单表格，前端框架每次渲染完以后，class 名字都带上不同的 hash 后缀，早上写的选择器下午就失效。这种问题用传统 JavaScript 写特别脆，你今天能抓到，明天页面改一下布局就全部白写。

第二座是输出格式不稳定。模型返回的东西是大段自然语言，你得抽字段、转 JSON、做校验。我的经验是只要你认真做一次"模型自由输出 -> 结构化数据"的转换，你就会明白为什么这么多团队专门做解析层。提示词写"只返回 JSON"远不够，模型还是会夹带解释文字、markdown 代码块标记、甚至把 null 写成 undefined。

第三座是页面交互的碎片化。扩展脚本要填写表单、点击按钮、跳转页面、取验证码、读 toast 消息，每一个动作都要自己封装一套 message 通信。要开个新页面？内存管理你得自己管。要跨字段存状态？localStorage 存储结构全自己设计。

1.2 Superpowers 的解题思路

Superpowers 的思路一句话就能说清：把浏览器操作能力变成 AI Agent 的工具箱，再把工具箱的调度封装成标准化 pipeline。你在代码里定义几个 input 槽位，告诉 Agent"这一步从页面上提取价格信息"，剩下的 DOM 解析、节点定位、模型参数调度、错误重试都交给框架。

我用了一个周末做技术验证，核心代码量大概长这样：

import { Agent, tools, InMemoryStore } from 'superpowers'; const agent = new Agent({ model: 'openai/gpt-4o', apiKey: process.env.SUPERPOWERS_API_KEY, tools: [ tools.navigate(), tools.extractData(), tools.click(), tools.inputText(), ], }); await agent.run( '打开报价单页面，提取所有产品的名称、单价和库存数量，返回 JSON', { store: new InMemoryStore() } );

我只写了一个 run 调用，页面加载、字段识别、数据提取、结果整理全部一次搞定。当时我心里只有一个想法：这个方向对了。特别是 tools 的可插拔设计，后面的定制空间非常大。你不用为了加一个操作类型去改动框架核心，注册一个新工具就行。

2. 安装与工程搭建

说干就干。Superpowers 的安装本身不复杂，但有几个环节容易踩坑，我把值得注意的都标记出来。

2.1 脚手架与依赖安装

我是基于 Vite + TypeScript 搭的项目，Chrome 扩展这边用 Manifest V3。初始化项目就不细说了，直接用 Vite 的模板就行。关键是依赖：

npm install superpowers

装完以后你会得到一个完整的 SDK，核心包括 Agent 管道、页面工具集、存储抽象层、以及和内容脚本通信的消息层。如果你的扩展不需要 UI，也可以拆开按需引入，但第一版我建议直接全量引入，省得在模块路径上折腾。

有个点注意：Superpowers 底层依赖 WebSocket 做本地调试时的一些事件推送，如果你的构建环境有 CSP 限制，记得在 Manifest 里把相关域名加进 connect-src，不然后面调试 Agent 会摸不着头脑。这个问题我后面会在问题清单里再展开。

2.2 Manifest V3 配置要点

我的最小可运行配置长这样：

{ "manifest_version": 3, "name": "Quote Extractor", "version": "0.1.0", "permissions": ["storage", "activeTab", "scripting"], "host_permissions": ["<all_urls>"], "background": { "service_worker": "src/background/index.ts" }, "content_scripts": [ { "matches": ["<all_urls>"], "js": ["src/content/index.ts"] } ], "action": { "default_popup": "src/popup/index.html" } }

几个容易踩的点，我一个个列出来。

• storage权限不是给 localStorage 的，它是给 chrome.storage 用的，Superpowers 的持久化存储可以接到 chrome.storage 上，这样 Agent 的记忆可以在多个扩展页面之间共享。
• host_permissions用<all_urls>在开发阶段比较省事，但生产环境建议收窄到目标域名，一是安全，二是审核友好。
• Manifest V3 的 service worker 生命周期和普通后台页不一样，有 idle 会被干掉的问题。Superpowers 对这块做了状态持久化，但你自己写的事件监听也要注意不能依赖全局变量常驻。我一开始在 background 里存了一个全局变量放 Agent 实例，结果扩展休眠后唤醒就跑挂，后来改成从 storage 恢复状态才解决。

2.3 密钥与环境变量

调用模型的 API Key 建议放后台服务端，如果纯前端扩展直接嵌入 Key，用户一解包就能拿走。我当时图省事先放在process.env.SUPERPOWERS_API_KEY里，配合 Vite 的import.meta.env也能跑，但仅限本地开发。

如果你有后端，推荐走代理转发模式：

const agent = new Agent({ endpoint: 'https://api.yoursite.com/agent', // 不在前端暴露任何密钥 });

Superpowers 的 Agent 构造器支持自定义 endpoint，后面接你自家的网关，这样 Key 永远不会泄露到扩展包里。

3. 核心能力拆解：Agent、推理与页面工具

这部分是重头戏。我把 Superpowers 的核心模块拆开来讲，每个模块解决什么问题、适合什么场景，我会结合我那个报价单项目来展开。

3.1 Agent 管道是怎么工作的

Agent 是 Superpowers 的中枢，它维护了一条 pipeline，每个阶段有明确职责。简化来看，一个 run 调用大致会走：

• 接收任务描述和初始状态
• 判断是否需要调用工具（页面导航、数据提取、点击、输入）
• 执行工具并收集结果
• 把结果纳入上下文并决定下一步
• 直到完成任务，输出最终结构化结果

核心模型是循环式 Agent：每轮先生成"行动决策"，有行动就执行工具，没有行动就输出答案。这种方式适合复杂任务，因为页面加载速度快慢不一，模型需要不断观察现场再决定下一步。

我举个真实例子，我的报价单提取任务描述是："进入最近一条未处理的报价单详情，提取表格里的产品名称、数量、单价，计算总金额，存到本地。"这个任务在传统脚本里要拆封面、判断表格形态、处理分页、还要防止页面还没加载完就抓数据。但在 Agent 管道里，它自己会判断"表格还没出现，等一等再提取"。

注意，这个能力是有代价的：为了稳定性，需要给工具调用加超时和重试机制。Superpowers 里工具超时默认配置比较保守，实测高延迟网络环境下 30 秒不够，我调到 60 秒才稳定。

3.2 结构化输出：不只是"让模型返回 JSON"

这个点值得单独讲。Superpowers 对结构化输出的处理不是简单地在提示词里加"请返回 JSON"，而是做了约束解码，保证工具返回的东西确实是合法 JSON。它支持你自定义 schema，框架会按照 schema 去引导模型输出。

比如报价单项目里我定义了一个提取格式：

import { z } from 'zod'; const QuoteSchema = z.object({ quoteId: z.string(), items: z.array(z.object({ name: z.string(), quantity: z.number(), unitPrice: z.number(), totalPrice: z.number(), })), totalAmount: z.number(), });

后面 Agent 提取出来的数据直接做schema.parse(output)就能进业务逻辑。这个看起来好像是个小优化，实际省了很多事。以前要写字段对齐、类型转换、容错处理，现在 parse 失败重跑一遍就行。

从工程的角度讲，这就是把"模型输出不可控"的短板用工程手段给挡了一道。凡是结构化需求强烈的地方——比如数据迁移、自动化录入、报表生成——这个能力都特别香。

3.3 页面工具集与内存管理

Superpowers 默认提供了几个常用工具：navigate负责跳转和等待加载，extractData负责数据提取，click负责模拟点击，inputText负责输入文本，storeValue负责跨步骤存储临时值。这些工具并不新鲜，但它做了一层统一的消息总线——工具在 background 里调用，实际跑在 content script 里，中间通信由框架接管。

后面我的项目扩展了侧边栏 UI，用户的输入参数需要从侧边栏传到 background 的 Agent，再让 Agent 驱动内容页产生操作。所有页面状态，比如定位到了哪里、读取到了什么，统一通过框架的 Memory 模块管理。Memory 解决的是多轮运行状态丢失问题：模型每轮调用都是独立的，但页面状态、中间提取结果、任务进度都在 Memory 里保存，下次调用接着用。简单说，它给 Agent 加了一个短期工作记忆。

Memory 的存储接口是抽象的，默认可以接到 Chrome storage 或者 IndexedDB，主要的记忆粒度是"域名 + 任务 + 字段"。如果你要跑多个站点的不同自动化，这个设计很省心。

4. 实操：做一个自动报价单录入扩展

理论讲完，直接落地。这个小项目是我的真实场景：每天要在后台系统里录入几十张报价单，手动点来点去太痛苦。用 Superpowers 做一个自动录入器，目标页面载入以后自动识别表单字段、自动填入、自动校验。

4.1 页面长什么样

为了演示，我把目标页面简化为一个包含四个字段的报价表单：客户名称、产品型号、数量、单价，还有一个提交按钮。页面有基本的 HTML form，不是 SPA 那种动态渲染。真实页面比这复杂，但核心流程一致。

4.2 核心代码拆解

后台脚本负责创建 Agent 并执行任务。这里我把工具集明确列出，并用 Memory 存跨域名数据。

import { Agent, tools } from 'superpowers'; async function handleAutoFill(tabId: number, formData: FormData) { const agent = new Agent({ model: 'openai/gpt-4o', tools: [ tools.navigate(), tools.extractData({ schema: { customerName: '客户名称', productModel: '产品型号', quantity: '数量', unitPrice: '单价', }, }), tools.inputText(), tools.click(), ], }); await agent.run(` 请检查当前页面中的表单字段，如果存在客户名称、产品型号、数量和单价字段， 分别填写以下数据，然后点击提交按钮。提交前先确认字段内容正确。 数据如下： ${JSON.stringify(formData)} `); }

click 之前先extractData把当前表单填充后的内容读出来，等于给 Agent 一个自检环节，这步很关键，能避免误填。我的策略是"填完必读回"，实测能拦截大约两成误操作场景。

4.3 内容脚本桥接

Superpowers 的消息层会自动在 background 和 content script 之间转发工具调用，你需要做的只是在 content script 里挂一个初始化入口：

import { bridgeContent } from 'superpowers/content'; bridgeContent();

就这样。框架会自动监听来自后台的工具调用，在页面上执行 DOM 操作，并把结果通过消息返回。没有手动定义消息监听器这一步，你也不用关心chrome.tabs.sendMessage这类 API。

4.4 本地运行与调试

在 Vite 项目里跑npm run dev，把生成的dist目录载入chrome://extensions的"加载已解压的扩展程序"就行。Superpowers 在 debug 模式下会输出完整的 Agent 决策日志，我强烈建议第一遍跑的时候全程开着日志，字段识别错了、点击选错按钮都能直接定位。日志路径在 DevTools 的 Service Worker 控制台里，不是页面控制台，第一次找的时候容易找错。

5. 常见问题与排查技巧实录

这块是我最想分享的，因为官方文档没写的坑全在实战里。

5.1 问题速查表

5.2 三个细节经验

第一，表单填写速度要控制。不要一次性把所有 input 事件都触发完。Superpowers 默认按字段逐个填入，中间会有短暂停顿，这其实是好事，因为页面上的 Vue/React 监听器需要时间响应。如果你的页面特别吃状态更新，可以在inputText工具的配置里加delay: { min: 200, max: 800 }，让输入节奏更接近真人，减少漏填。

第二，model 的选择很重要。虽然 Superpowers 兼容多种模型，但我实测下来，简单表单填充用小参数模型就能搞定，复杂多步骤任务就得用更大尺寸的模型。花哨的提示词拯救不了小模型的判断力。项目里我做了一个根据任务复杂度切换模型的逻辑，简单任务用快速模型，复杂任务换强模型，成本控制得非常明显。

第三，钩子要比全自动稳妥。不要一上来就做全自动逐单处理，先做一个"半自动确认"版本：Agent 填写完表单后，弹一个确认按钮，人工看一眼再提交。跑了两天数据稳定后再把确认环节去掉。这个循序渐进的做法能省掉大量调试返工时间。

6. 性能与成本控制：别让 AI 把你的扩展拖垮

最后一个必须聊的话题。AI 扩展跑起来以后，你会在两个地方有明显感知：每次任务执行要等模型返回，Token 消耗带来的成本。这两点如果不管控，功能做得再强也上不了生产。

6.1 Token 消耗的关键优化

最费 Token 的是 Agent 的决策日志——每轮工具调用都要把当前页面提取的文本、上一步操作结果、任务描述全部塞进上下文。页面越长，Token 越夸张。我的做法是限制extractData的输入长度。只提取当前可见区域的关键字段，而不是整页文本。

另一个优化是减少不必要的重试。有一次价格字段一直提取不对，仔细看了日志发现是模型在纠结单位换算，而我压根没让它算。后来在提示词里明写"不要换算，提取原始数值"，错误率直接降下来。提示词写清楚边界，永远比重试经济。

6.2 本地存储与历史记录

建议用 chrome.storage 保存每次任务的运行记录，包括输入、输出、耗时、Token 用量。后面你优化模型、调整提示词、更换 schema 的时候，这些历史记录是最好的回归测试集。我大概存了三百条运行记录以后，发现有几个页面的结构变化被模型自动适应了，传统脚本根本做不到这一点。

6.3 生产部署的三个建议

• 后台转服务端调用模型，避免 Key 泄露。
• 给 Agent 任务加超时和最大轮数，防止死循环烧 Token。
• 把长任务的进度通过扩展图标实时展示，用户体验好很多。

我踩过一次大坑：没设最大轮数，结果 Agent 在某个登录页反复尝试了十几分钟才退出，账单直接难看。从那以后我养成了习惯，任何 Agent 任务都必须设上限，既保护钱包也保护用户体验。

写在最后的一点体会

从写成百上千行 DOM 操作代码到现在用一段自然语言描述任务，这个变化是我做浏览器扩展以来最明显的效率拐点。Superpowers 的价值不只是省代码，而是让"让 AI 理解页面状态、决策下一步操作"这件事变成了扩展开发的标准能力。当然它也不是银弹，页面极度不规则、流程极其复杂的场景，还是需要你把少量规则逻辑嵌进提示词或工具实现里。我的体会是：先用最小闭环跑通你的核心场景，再逐步加工具、加校验、加记忆，别一上来就追求全自动。你会在实际迭代中慢慢找到最适合自己项目的 AI 和规则的平衡点。