Activepieces 社区 Piece 构建实战以 PhantomBuster 为例【免费下载链接】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本篇以 PhantomBuster piece 为具体对象讲清 Activepieces 社区 piece 库的构建入口、Turbo 任务编排与 TypeScript 产物配置。读完后可独立完成该 piece 的构建、产物核验并理解 piece 的鉴权、Action、Trigger 三层结构为自研同类社区 piece 提供参考。1. 构建命令与产物README 明确给出了构建入口turbo run build --filteractivepieces/piece-phantombuster该命令通过--filter精确锁定activepieces/piece-phantombuster这一个包仅构建它及其依赖上游。对应的包脚本在 package.json 中定义为build: tsc -p tsconfig.lib.json cp package.json dist/即先用tsconfig.lib.json做编译再把package.json拷入dist/最终产物入口为dist/src/index.js、类型声明为dist/src/index.d.ts见main/types字段。1.1 Turbo 的 build 任务编排在根目录 turbo.json 中build任务的声明为build: { dependsOn: [^build], outputs: [], inputs: [ src/**, tsconfig*.json, package.json, !src/**/*.spec.ts, !src/**/*.test.ts, !vitest.config.* ], cache: false }dependsOn: [^build]先构建依赖项如activepieces/pieces-framework、activepieces/pieces-common等 workspace 包。cache: false每次真实执行编译不做增量缓存。inputs排除测试与 vitest 配置保证构建输入稳定。2. TypeScript 编译配置构建使用的 tsconfig.lib.json 继承自 tsconfig.json后者再继承仓库根目录的tsconfig.base.json{ extends: ./tsconfig.json, compilerOptions: { rootDir: ., baseUrl: ., paths: {}, outDir: ./dist, declaration: true, declarationMap: true, types: [node] }, include: [src/**/*.ts] }要点outDir: ./dist与包声明的产物路径一致declaration: truedeclarationMap: true产出.d.ts与映射供上层引用类型include仅覆盖src/**/*.ts测试文件不进库产物。父级 tsconfig.json 开启strict、noImplicitReturns、noPropertyAccessFromIndexSignature等严格选项并以 project references 指向tsconfig.lib.json。3. Piece 源码结构构建对象的内容理解“在构建什么”需要看入口 src/index.ts。它用createPiece声明整个 piecedisplayName: PhantomBusterminimumSupportedRelease: 0.36.1categories: [PieceCategory.MARKETING, PieceCategory.SALES_AND_CRM]actions: [launchPhantom, createCustomApiCallAction(...)]triggers: [newOutput]auth: phantombusterAuth。其中createCustomApiCallAction基于BASE_URL生成一个通用“自定义 API 调用”Action并通过authMapping把密钥写入请求头。3.1 鉴权SecretText 与校验auth.ts 使用PieceAuth.SecretText定义“API Token”并在validate中发起GET /agents/fetch-all探测密钥有效性失败时返回Invalid API key or insufficient permissions。3.2 HTTP 客户端与 BASE_URLclient.ts 定义export const BASE_URL https://api.phantombuster.com/api/v2;makeRequest统一注入X-Phantombuster-Key与Content-Type: application/json头供鉴权校验、Action、下拉属性复用是 piece 内所有出站请求的收敛点。3.3 公共属性Agent 下拉props.ts 定义agentIdDropdown调用GET /agents/fetch-all将返回的每个 agent 映射为{ label: name createdAt, value: id }若鉴权未配置则返回disabled占位。3.4 ActionLaunch Phantomlaunch-phantom.ts 的run组装{ id: agentId }按需追加argument、maxRetriesPOST /agents/launch入队执行若勾选waitForOutput则以 5 秒间隔轮询GET /agents/fetch-output?id...直到status命中finished / error / unknown后返回输出否则直接返回 launch 响应。3.5 TriggerNew OutputWebhooknew-output.ts 采用TriggerStrategy.WEBHOOKrun中通过output.agentId context.propsValue.agentId过滤仅放行属于所选 agent 的回调事件sampleData展示了agentId / containerId / resultObject / exitMessage / exitCode等字段结构。4. 依赖与打包dependencies均引用 workspace 内件activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils外加semver7.6.0。package.json还提供bundlepieces bundle与lint脚本构建后如需独立分发可再跑bundle生成dist/index.bundle.js对应 turbo.json 中bundle任务的outputs。小结该 piece 的构建链路是turbo run build --filteractivepieces/piece-phantombuster→ 先^build上游 → 本包tsc -p tsconfig.lib.json产出dist/src含.d.ts→cp package.json dist/。源码上由auth.tsSecretText 鉴权与校验、client.ts统一请求与 BASE_URL、props.tsAgent 下拉、launch-phantom.tsLaunch Action与new-output.tsWebhook Trigger共同构成一个可直接运行的社区 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Activepieces 社区 Piece 构建实战：以 PhantomBuster 为例
Activepieces 社区 Piece 构建实战以 PhantomBuster 为例【免费下载链接】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本篇以 PhantomBuster piece 为具体对象讲清 Activepieces 社区 piece 库的构建入口、Turbo 任务编排与 TypeScript 产物配置。读完后可独立完成该 piece 的构建、产物核验并理解 piece 的鉴权、Action、Trigger 三层结构为自研同类社区 piece 提供参考。1. 构建命令与产物README 明确给出了构建入口turbo run build --filteractivepieces/piece-phantombuster该命令通过--filter精确锁定activepieces/piece-phantombuster这一个包仅构建它及其依赖上游。对应的包脚本在 package.json 中定义为build: tsc -p tsconfig.lib.json cp package.json dist/即先用tsconfig.lib.json做编译再把package.json拷入dist/最终产物入口为dist/src/index.js、类型声明为dist/src/index.d.ts见main/types字段。1.1 Turbo 的 build 任务编排在根目录 turbo.json 中build任务的声明为build: { dependsOn: [^build], outputs: [], inputs: [ src/**, tsconfig*.json, package.json, !src/**/*.spec.ts, !src/**/*.test.ts, !vitest.config.* ], cache: false }dependsOn: [^build]先构建依赖项如activepieces/pieces-framework、activepieces/pieces-common等 workspace 包。cache: false每次真实执行编译不做增量缓存。inputs排除测试与 vitest 配置保证构建输入稳定。2. TypeScript 编译配置构建使用的 tsconfig.lib.json 继承自 tsconfig.json后者再继承仓库根目录的tsconfig.base.json{ extends: ./tsconfig.json, compilerOptions: { rootDir: ., baseUrl: ., paths: {}, outDir: ./dist, declaration: true, declarationMap: true, types: [node] }, include: [src/**/*.ts] }要点outDir: ./dist与包声明的产物路径一致declaration: truedeclarationMap: true产出.d.ts与映射供上层引用类型include仅覆盖src/**/*.ts测试文件不进库产物。父级 tsconfig.json 开启strict、noImplicitReturns、noPropertyAccessFromIndexSignature等严格选项并以 project references 指向tsconfig.lib.json。3. Piece 源码结构构建对象的内容理解“在构建什么”需要看入口 src/index.ts。它用createPiece声明整个 piecedisplayName: PhantomBusterminimumSupportedRelease: 0.36.1categories: [PieceCategory.MARKETING, PieceCategory.SALES_AND_CRM]actions: [launchPhantom, createCustomApiCallAction(...)]triggers: [newOutput]auth: phantombusterAuth。其中createCustomApiCallAction基于BASE_URL生成一个通用“自定义 API 调用”Action并通过authMapping把密钥写入请求头。3.1 鉴权SecretText 与校验auth.ts 使用PieceAuth.SecretText定义“API Token”并在validate中发起GET /agents/fetch-all探测密钥有效性失败时返回Invalid API key or insufficient permissions。3.2 HTTP 客户端与 BASE_URLclient.ts 定义export const BASE_URL https://api.phantombuster.com/api/v2;makeRequest统一注入X-Phantombuster-Key与Content-Type: application/json头供鉴权校验、Action、下拉属性复用是 piece 内所有出站请求的收敛点。3.3 公共属性Agent 下拉props.ts 定义agentIdDropdown调用GET /agents/fetch-all将返回的每个 agent 映射为{ label: name createdAt, value: id }若鉴权未配置则返回disabled占位。3.4 ActionLaunch Phantomlaunch-phantom.ts 的run组装{ id: agentId }按需追加argument、maxRetriesPOST /agents/launch入队执行若勾选waitForOutput则以 5 秒间隔轮询GET /agents/fetch-output?id...直到status命中finished / error / unknown后返回输出否则直接返回 launch 响应。3.5 TriggerNew OutputWebhooknew-output.ts 采用TriggerStrategy.WEBHOOKrun中通过output.agentId context.propsValue.agentId过滤仅放行属于所选 agent 的回调事件sampleData展示了agentId / containerId / resultObject / exitMessage / exitCode等字段结构。4. 依赖与打包dependencies均引用 workspace 内件activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils外加semver7.6.0。package.json还提供bundlepieces bundle与lint脚本构建后如需独立分发可再跑bundle生成dist/index.bundle.js对应 turbo.json 中bundle任务的outputs。小结该 piece 的构建链路是turbo run build --filteractivepieces/piece-phantombuster→ 先^build上游 → 本包tsc -p tsconfig.lib.json产出dist/src含.d.ts→cp package.json dist/。源码上由auth.tsSecretText 鉴权与校验、client.ts统一请求与 BASE_URL、props.tsAgent 下拉、launch-phantom.tsLaunch Action与new-output.tsWebhook Trigger共同构成一个可直接运行的社区 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考