Activepieces 集成 Serpstat：关键词分析 Piece 的配置、使用与源码实现解析

Activepieces 集成 Serpstat：关键词分析 Piece 的配置、使用与源码实现解析

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

本文以仓库中的 serpstat 组件说明文档 为主线，结合@activepieces/piece-serpstat的完整源码实现，讲解如何在 Activepieces 中接入 Serpstat 关键词分析能力：从 API Token 认证配置、两个核心 Action（Get Keywords / Get Suggestions）的每个参数含义，到底层 JSON-RPC 式请求的组装逻辑，以及该 Piece 在 Turbo 单仓中的构建与打包方式。读完本文，你将能熟练地在自己的自动化流程中配置并调用 Serpstat 关键词数据，也能读懂该 Piece 的源码结构，为二次开发或贡献新 Action 打下基础。

一、Piece 概览：它给 Activepieces 带来了什么

serpstat是 Activepieces 社区组件库（packages/pieces/community/）下的一个生产力类（Productivity）Piece，包名为@activepieces/piece-serpstat。从 组件注册入口 index.ts 可以看到它的元信息：

• displayName：Serpstat
• 分类：PieceCategory.PRODUCTIVITY（生产力工具）
• 最低支持的 Activepieces 版本：0.36.1
• 作者：geekyme
• Action 清单：Get Keywords、Get Suggestions，以及一个通用的Custom API Call动作
• Triggers：无（该 Piece 只提供主动查询能力，不监听事件）

在 package.json 中记录当前版本为0.1.7，运行时依赖@activepieces/pieces-common、@activepieces/pieces-framework、@activepieces/core-piece-types、@activepieces/core-utils四个工作区内部包，说明它完全构建在 Activepieces 的组件框架之上。

Serpstat 是一款 SEO 关键词研究与竞争分析工具，其公开 API 提供关键词数据查询能力。本 Piece 把这些能力封装成可视化、可拖拽的流程节点，让用户无需编写 HTTP 请求代码，就能在流程中获取关键词的搜索量、CPC、竞争度等数据。

二、认证配置：API Token 的获取与自动校验

Serpstat Piece 使用「密钥文本」（SecretText）作为认证方式，实现在 lib/common/auth.ts：

• 在 Activepieces 中创建 Serpstat 连接时，只需填入一个字段：API Token（必填）。Token 可以从 Serpstat 账户后台的 API Settings 页面获取。
• 该 Piece 内置了连接校验逻辑：保存连接时，Activepieces 会向https://api.serpstat.com/v4/发送一次GET请求（带token查询参数）来验证凭证有效性：
  • 若返回401，提示Invalid API token. Please check your token and try again.；
  • 其余失败情况统一提示Authentication failed. Please check your API token.；
  • 只有校验通过才会保存连接，避免把无效 Token 带进流程。

值得注意的是，验证请求发送到的是 Serpstat API 的根路径/v4/，而实际业务请求统一走https://api.serpstat.com/v4（见下文）。认证信息在每次调用时以token查询参数注入请求——这是 Serpstat API 的鉴权约定，与常见的 Bearer Header 方式不同，配置代理或网关时需要注意这一点。

三、核心 Action 详解（一）：Get Keywords 关键词查询

Get Keywords是关键词分析模块（lib/actions/keyword-analysis/）下的第一个动作，实现在 get-keywords.ts。它的用途是：给定一个种子关键词，返回该词在指定搜索引擎/区域下的自然排名关键词数据（搜索量、CPC、竞争度等），用于研究某一词周边的关键词格局。

3.1 全部输入参数

3.2 请求参数的组装逻辑

run()函数中有一段清晰的参数拼装逻辑，值得展开：

• 必带参数：keyword、se、page、size；
• 若填了minusKeywords，原样透传（数组）；
• 若填了withIntents，透传布尔值；
• 只有当sortField与sortOrder同时存在时，才组装嵌套的sort对象：{ [sortField]: sortOrder }，即{ "search_volume": "desc" }这样的结构；
• 若填了filters，透传 JSON 对象。

最终请求体是一个带随机id（由crypto.randomUUID()生成）的 JSON-RPC 风格对象：

{ "id": "6f9c1e2a-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "method": "SerpstatKeywordProcedure.getKeywords", "params": { "keyword": "activepieces", "se": "g_us", "page": 1, "size": 10, "minusKeywords": ["-free"], "sort": { "search_volume": "desc" } } }

方法名SerpstatKeywordProcedure.getKeywords与 Serpstat v4 公共 API 的方法命名保持一致，说明该 Piece 是对 Serpstat 官方接口的薄封装。

四、核心 Action 详解（二）：Get Suggestions 关键词建议

Get Suggestions实现在 get-suggestions.ts，用途是：返回与种子关键词相关的搜索建议（包含该词的全文匹配变体、长尾词），适合做关键词灵感挖掘。

4.1 输入参数

与 Get Keywords 相比，它更轻量：不提供 minus keywords、intents、排序等选项，且默认size为 100（Keywords 的默认 size 是 10）。请求体同样采用 JSON-RPC 风格，方法名为SerpstatKeywordProcedure.getSuggestions：

{ "id": "a3b8c5d0-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "method": "SerpstatKeywordProcedure.getSuggestions", "params": { "keyword": "seo", "se": "g_us", "page": 1, "size": 100 } }

4.2 面向 AI Agent 的元数据标注

这两个 Action 都声明了aiMetadata，这是 Activepieces 为 AI Agent 场景提供的机器可读描述。例如 Get Keywords 的aiMetadata注明该动作「只读、幂等（idempotent: true）」，并概述了其能力边界（支持排除负向词、排序、分页、高级过滤器）。这意味着该 Piece 不仅能在可视化流程画布中使用，也能被平台内的 AI 工具发现并正确调用——这是理解它在现代 AI 工作流中定位的关键细节。

五、底层调用机制：统一 API 客户端与 Custom API Call

5.1 统一的serpstatApiCall封装

所有业务请求都经过 lib/common/client.ts 中的serpstatApiCall函数：

• 基准地址：BASE_URL = 'https://api.serpstat.com/v4'（注意：与认证校验用的/v4/带斜杠版本不同）；
• 每个请求自动附加token查询参数（来自连接中保存的 Token），其余查询参数通过...queryParams展开合并；
• 设置Content-Type: application/json请求头；
• 统一走httpClient.sendRequest（来自@activepieces/pieces-common），返回response.body。

由于两个 Action 都调用resourceUri: '/'，最终请求 URL 即https://api.serpstat.com/v4/，方法与参数全部放在 JSON body 中——这就是 Serpstat v4 API 的调用方式。

5.2 内置的 Custom API Call 逃生通道

在 组件注册入口 中，除了两个封装好的 Action，还注册了一个createCustomApiCallAction，它向用户暴露了完整的 Serpstat API 能力：

• baseUrl固定为BASE_URL；
• 认证位置为queryParams，自动把token注入每个自定义请求的查询参数中。

也就是说，即使内置 Action 无法覆盖某个接口，用户依然可以在流程中用「Custom API Call」节点直接调用 Serpstat v4 的任何端点，同时免去手动填写 Token 的麻烦。从 i18n/translation.json 可以看到，该自定义请求节点支持 Method、Headers、Query Parameters、Body、超时、跟随重定向、二进制响应等通用配置项，与框架内置行为一致。

六、支持的搜索引擎选项

搜索引擎选项集中在 lib/common/search-engines.ts，目前内置 6 个地区：

选项明显侧重东南亚市场（新加坡、印尼、马来西亚、越南、泰国）加美国。两个 Action 的Search Engine下拉框都复用这份常量表，默认值为g_us。

需要留意一个细节：With Intents参数（Get Keywords）的描述注明「仅对g_au（澳大利亚）与g_us（美国）生效」，但当前下拉选项中并未提供g_au。也就是说，在现有内置选项下，该意图开关实际上主要针对g_us生效；若需要澳大利亚数据，可以通过 Custom API Call 直接传g_au参数。这属于源码中「描述能力」与「预设选项」不完全对齐的边界情况，使用时应结合 Serpstat 官方文档确认。

七、构建、打包与多语言支持

7.1 构建命令

组件说明文档 README.md 给出了构建方式，这也是 Activepieces 单仓（monorepo，使用 Turborepo 管理）的标准做法：

turbo run build --filter=@activepieces/piece-serpstat

--filter精确锁定@activepieces/piece-serpstat这个包，只会构建它及其依赖链，不会触发全仓构建。该命令实际执行的是 package.json 中定义的build脚本：

tsc -p tsconfig.lib.json && cp package.json dist/

即先用 TypeScript 编译器按tsconfig.lib.json的库构建配置把src/编译到dist/，再把package.json复制进dist/，保证产物目录是一个可独立解析的 CommonJS 包（"type": "commonjs"，入口为./dist/src/index.js）。另外还提供了：

• bundle：调用 Activepieces CLI 的pieces bundle子命令，把 Piece 打包成可在运行时加载的 bundle；
• lint：对src/**/*.ts运行 ESLint。

7.2 多语言国际化

该 Piece 的 UI 文案全部走 i18n 机制，i18n/ 目录下提供了translation.json（默认英文）及de、es、fr、ja、nl、pt、zh共 7 种语言映射文件。从 translation.json 可以看到，从认证提示、Action 名称到每个参数的描述文案都被纳入了翻译键体系。这意味着在非英文界面的 Activepieces 中，Serpstat 节点的显示文案会自动本地化。

八、实战：在流程中使用 Serpstat 节点的推荐姿势

综合上述源码事实，给出几条可落地的使用建议：

1. 先建连接再建流程：在连接管理中创建 Serpstat 连接并填入 API Token，保存时框架会自动校验 Token 有效性（401会立即报错），确保后续节点不会因凭证问题失败。
2. 关键词调研用 Get Keywords：填入种子词、选择目标地区（默认美国）、按需设置Sort Field = search_volume且Sort Order = desc可快速拿到该词下搜索量最高的一批相关词；Size最大 100，注意配合Page做分页拉全。
3. 扩词灵感用 Get Suggestions：它的默认Size就是 100，适合一次性批量拉取长尾变体；需要精确缩小范围时再用FiltersJSON。
4. 过滤语法吃不准时：Filters是高级能力，两个 Action 的字段描述都指向 Serpstat 官方 API 文档中的对应方法页以说明精确语法，配置复杂过滤条件前建议先查阅官方文档确认字段名与操作符。
5. 内置 Action 覆盖不了时：直接用 Piece 自带的 Custom API Call 节点，Token 会自动注入，你只需要填资源路径、方法与参数，即可触达 Serpstat v4 全部接口。

九、总结

Serpstat Piece 是 Activepieces 社区生态中一个「小而精」的 SEO 集成：它以两个参数化良好的 Action 覆盖了关键词数据查询与建议挖掘两大高频场景，通过 JSON-RPC 风格请求直连 Serpstat v4 API，并借助统一的 API 客户端与 Custom API Call 兜底保持了接口的完整可达性；认证层内置 Token 校验、UI 文案全量国际化，再加上标准的 Turbo 构建管线（turbo run build --filter=@activepieces/piece-serpstat），让它可以无缝融入 Activepieces 的流程画布与 AI Agent 工具生态。对于需要把 SEO 数据接入自动化工作流的开发者而言，无论是直接使用还是参考其源码封装新的 SEO 类集成，这份实现都提供了清晰且可复用的范式。

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces