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 --filter=@activepieces/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: true+declarationMap: true产出.d.ts与映射，供上层引用类型；
include仅覆盖src/**/*.ts，测试文件不进库产物。

父级 tsconfig.json 开启strict、noImplicitReturns、noPropertyAccessFromIndexSignature等严格选项，并以 project references 指向tsconfig.lib.json。

3. Piece 源码结构（构建对象的内容）

理解“在构建什么”，需要看入口 src/index.ts。它用createPiece声明整个 piece：

displayName: 'PhantomBuster'，minimumSupportedRelease: '0.36.1'；
categories: [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_URL

client.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 Action：Launch Phantom

launch-phantom.ts 的run：

组装{ id: agentId }，按需追加argument、maxRetries；
POST /agents/launch入队执行；
若勾选waitForOutput，则以 5 秒间隔轮询GET /agents/fetch-output?id=...，直到status命中finished / error / unknown后返回输出，否则直接返回 launch 响应。

3.5 Trigger：New Output（Webhook）

new-output.ts 采用TriggerStrategy.WEBHOOK，run中通过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，外加semver@7.6.0。package.json还提供bundle（pieces bundle）与lint脚本，构建后如需独立分发可再跑bundle生成dist/index.bundle.js（对应 turbo.json 中bundle任务的outputs）。

小结

该 piece 的构建链路是：turbo run build --filter=@activepieces/piece-phantombuster→ 先^build上游 → 本包tsc -p tsconfig.lib.json产出dist/src（含.d.ts）→cp package.json dist/。源码上由auth.ts（SecretText 鉴权与校验）、client.ts（统一请求与 BASE_URL）、props.ts（Agent 下拉）、launch-phantom.ts（Launch Action）与new-output.ts（Webhook Trigger）共同构成一个可直接运行的社区 piece。