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 认证配置、两个核心 ActionGet Keywords / Get Suggestions的每个参数含义到底层 JSON-RPC 式请求的组装逻辑以及该 Piece 在 Turbo 单仓中的构建与打包方式。读完本文你将能熟练地在自己的自动化流程中配置并调用 Serpstat 关键词数据也能读懂该 Piece 的源码结构为二次开发或贡献新 Action 打下基础。一、Piece 概览它给 Activepieces 带来了什么serpstat是 Activepieces 社区组件库packages/pieces/community/下的一个生产力类ProductivityPiece包名为activepieces/piece-serpstat。从 组件注册入口 index.ts 可以看到它的元信息displayNameSerpstat分类PieceCategory.PRODUCTIVITY生产力工具最低支持的 Activepieces 版本0.36.1作者geekymeAction 清单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 全部输入参数参数类型必填默认值说明QueryShortText是—要查询的种子关键词Search EngineStaticDropdown是g_us目标搜索引擎/区域见第四节选项表Minus KeywordsArray否—需要排除的关键词列表负向关键词With IntentsCheckbox否—是否返回关键词意图源码描述注明仅g_au与g_us生效Sort FieldStaticDropdown否region_queries_count排序字段可选region_queries_count区域查询量、search_volume搜索量、cpc、competition竞争度、results_count结果数Sort OrderStaticDropdown否desc排序方向desc降序 /asc升序SizeNumber否10返回结果条数最大 100PageNumber否1分页页码FiltersJson否—高级 JSON 过滤器语法遵循 Serpstat 官方 API 文档该字段描述中内嵌了官方文档链接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 输入参数参数类型必填默认值说明KeywordShortText是—用于获取建议的种子关键词Search EngineStaticDropdown是g_us目标搜索引擎/区域FiltersJson否—高级 JSON 过滤器语法同 Get KeywordsPageNumber否1响应页码SizeNumber否100每页结果条数与 Get Keywords 相比它更轻量不提供 minus keywords、intents、排序等选项且默认size为 100Keywords 的默认 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 Call5.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 个地区地区Label取值ValueUnited Statesg_usSingaporeg_sgIndonesiag_idMalaysiag_myVietnamg_vnThailandg_th选项明显侧重东南亚市场新加坡、印尼、马来西亚、越南、泰国加美国。两个 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 --filteractivepieces/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 打包成可在运行时加载的 bundlelint对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 节点的推荐姿势综合上述源码事实给出几条可落地的使用建议先建连接再建流程在连接管理中创建 Serpstat 连接并填入 API Token保存时框架会自动校验 Token 有效性401会立即报错确保后续节点不会因凭证问题失败。关键词调研用 Get Keywords填入种子词、选择目标地区默认美国、按需设置Sort Field search_volume且Sort Order desc可快速拿到该词下搜索量最高的一批相关词Size最大 100注意配合Page做分页拉全。扩词灵感用 Get Suggestions它的默认Size就是 100适合一次性批量拉取长尾变体需要精确缩小范围时再用FiltersJSON。过滤语法吃不准时Filters是高级能力两个 Action 的字段描述都指向 Serpstat 官方 API 文档中的对应方法页以说明精确语法配置复杂过滤条件前建议先查阅官方文档确认字段名与操作符。内置 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 --filteractivepieces/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考