Activepieces Piece SDK 开发指南从脚手架到运行时上下文的完整实战【免费下载链接】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/activepiecesActivepieces 是一个开源 AI 工作流自动化平台其 400 集成全部以 Piece积木式能力包的形式存在。本文以仓库内 packages/pieces/CLAUDE.md 为骨架系统讲解如何从零创建一个 Piece包含脚手架命令、工程接入、目录结构、三种认证模式、run()内的完整运行时上下文Piece Context以及必须遵守的编码规则。读完本文你将能够独立为 Activepieces 贡献一个新的社区 Piece或基于 SDK 改造现有集成。快速开始三个脚手架命令Activepieces 通过 package.json 暴露了三个用于生成 Piece 骨架的命令它们底层都调用packages/cli的 TypeScript 入口packages/cli/src/index.tsnpm run create-piece # 创建一个全新的 Piece npm run create-action # 为已有 Piece 添加一个 Action npm run create-trigger # 为已有 Piece 添加一个 Trigger三条命令的实际执行链路分别对应 CLI 子命令pieces create、actions create、triggers create生成代码后即可在packages/pieces/community/{name}/下看到骨架文件。接入 tsconfig 路径映射创建完成后还需要把新 Piece 的入口注册到 tsconfig.base.json 的paths中形如activepieces/piece-{name}: [packages/pieces/community/{name}/src/index.ts]这一步让 TypeScript 能以activepieces/piece-{name}的形式解析新 Piece是 monorepo 内部引用与编译的前提。Piece 目录结构一个标准的社区 Piece 遵循统一的目录约定packages/pieces/community/{name}/ ├── src/index.ts # createPiece() 定义Piece 的入口与装配点 ├── src/lib/auth.ts # 认证配置SecretText / OAuth2 / CustomAuth ├── src/lib/actions/ # 每个 Action 一个文件 ├── src/lib/trigger/ # 每个 Trigger 一个文件 ├── src/lib/common/ # API 辅助函数、共享 props └── src/i18n/translation.json # i18n 翻译文件仓库中 packages/pieces/community/airtable/ 是一个完整范例src/index.ts中通过createPiece()装配了 30 个 Action、2 个 Trigger 和认证对象见 airtable/src/index.tssrc/lib/actions/下每个文件对应一个 Action如 create-record.tssrc/lib/trigger/下是轮询型触发器如 new-record.trigger.tssrc/i18n/下除translation.json外还包含多语言版本zh、ja、fr 等。三种认证模式Auth PatternsSDK 通过PieceAuth提供三种内置认证类型且都支持validate回调用于校验凭据模式适用场景关键点PieceAuth.SecretText()API Key / Token常用validate回调做真实请求校验PieceAuth.OAuth2()标准 OAuth2 授权由平台托管授权流程与令牌刷新PieceAuth.CustomAuth({ props })多字段凭据自定义字段组合如{ username, password }以 Airtable 的 auth.ts 为例SecretText的validate回调直接向目标 API 发一个真实请求来确认令牌有效性export const airtableAuth PieceAuth.SecretText({ displayName: Personal Access Token, required: true, description: ...获取令牌的步骤说明..., validate: async (auth) { try { await httpClient.sendRequest({ method: HttpMethod.GET, url: https://api.airtable.com/v0/meta/bases, authentication: { type: AuthenticationType.BEARER_TOKEN, token: auth.auth, }, }); return { valid: true }; } catch (e) { return { valid: false, error: Invalid personal access token }; } }, });validate返回{ valid: boolean, error?: string }校验通过时用户在画布上能顺利保存连接失败时则携带可读错误信息。三种认证在框架层的类型定义可参见 framework/src/lib/property/authentication/。从源码结构可以推断createPiece()还要求同一 Piece 的多个认证属性传入数组时按类型唯一否则直接抛错Auth properties must be unique by type见 framework/src/lib/piece.ts。Piece Contextrun()内的完整运行时能力Action 与 Trigger 的run(context)接收一个类型化的context对象这是 Piece 与 Activepieces 引擎交互的唯一通道。以下按使用场景逐一说明context.auth— 已解析的凭据运行时经过平台解密、解析后的连接凭据。其具体结构由 Piece 的认证类型推导SecretText得到{ secret_text }OAuth2得到{ access_token, ... }CustomAuth得到自定义字段对象。类型推导逻辑见 framework/src/lib/context/index.ts因此run()内访问context.auth是类型安全的。context.propsValue— 已解析的输入属性用户在画布上为 Action 填写的props经过解析后的值。Airtable 的 create-record.ts 展示了典型用法从context.propsValue取出base、tableId、fields过滤空值后再组装请求。context.store— 跨执行持久化的键值存储用于在多次执行之间保存状态如游标、去重标记context.store.putT(key, value, scope?): PromiseT context.store.getT(key, scope?): PromiseT | null context.store.delete(key, scope?): Promisevoidscope支持StoreScope.PROJECT项目级兼容历史值COLLECTION与StoreScope.FLOW流程级接口定义见 framework/src/lib/context/index.ts。context.files— 文件上传/下载重点context.files.write({ fileName, data })的data既接受Buffer也接受Readable流见FilesService接口 framework/src/lib/context/index.ts。当处理大文件时应把源流例如 S3getObject().Body直接传给write让文件在沙箱内边读边写、不经内存缓冲地流转到对象存储const s3Stream await s3.getObject({ Bucket, Key }).createReadStream(); await context.files.write({ fileName: large.bin, data: s3Stream });与之对应输入侧使用Property.File({ streaming: true })时属性值不再解析为缓冲在内存的ApFile而是ApStreamingFiletype ApStreamingFile { filename: string; extension?: string; size?: number; body: Readable; };类型定义见 framework/src/lib/property/input/file-property.ts。流式场景下需要遵循三条实践优先选择接受未知长度流的目标客户端如 S3lib-storage的Upload、AzureuploadStream、Google Drivemedia.body、SFTPclient.putsize是尽力而为的值对 chunked 编码或Content-Encoding压缩过的源流size会缺失因此只有当目标 API 强制要求Content-Length时才去读取它httpClient不会重试流式 body当请求体是Readable或form-data时retries被强制为0——因为重试循环会重放一个已被消费的流导致发出截断的 body。如果确实需要重试请先把 body 缓冲为Buffer。context.connections— 连接管理运行时管理 OAuth 等连接对象的入口支持按 key 获取连接值ConnectionsManager.get(key)见 framework/src/lib/context/index.ts。context.server— API 访问信息提供token内部 API 令牌、apiUrl、publicUrl三个字段ServerContext见 framework/src/lib/context/index.ts用于调用 Activepieces 自身 API 或拼接回调地址。流程控制stop / pause / respondAPI行为context.run.stop({ response })停止流程直接返回 HTTP 响应context.run.pause({ pauseMetadata })暂停流程等待延时到期或 Webhook 回调后恢复context.run.respond({ response })先发送响应流程继续执行需要说明的是源码中pause自 2026-04-12 起标记为deprecated引擎层面推荐改用context.run.createWaitpoint(...)创建DELAY/WEBHOOK等待点并返回resumeUrl配合context.run.waitForWaitpoint(...)的组合见 framework/src/lib/context/index.ts。新写的 Piece 应优先使用新的 waitpoint 原语。其他上下文能力context.agent.tools()为 AI Agent 构建工具Agent 侧工具注册context.generateResumeUrl()为暂停的流程生成 Webhook 恢复地址同样处于废弃过渡期优先使用 waitpoint 返回的buildResumeUrlcontext.executionTypeBEGIN表示流程初次执行RESUME表示暂停后恢复执行据此可区分分支逻辑ActionContext联合类型见 framework/src/lib/context/index.ts。关键规则Key Rules编写 Piece 时必须遵守以下约定否则无法通过构建、测试或无法被画布正确渲染Trigger 的run()必须返回数组。无论轮询还是 Webhook 触发返回值都必须是元素数组引擎按元素逐条下发。可对照 new-record.trigger.ts 中pollingHelper.poll的返回值使用方式HTTP 请求统一使用activepieces/pieces-common的httpClient。它封装了认证注入、错误处理与限流逻辑禁止直接裸写fetch/axiosAirtable 的 auth.ts 是标准用法示例Trigger 必须提供sampleData。画布上的测试触发器依赖它渲染示例输出缺失会导致测试功能不可用i18n维护src/i18n/translation.json使用与 key 同名的英文值identity mapping作为默认翻译平台据此做多语言展示。源码级理解createPiece/createAction/createTrigger理解三个工厂函数的底层契约能帮你写出更规范的 Piece。createPiececreatePiece()返回Piece实例framework/src/lib/piece.ts其参数契约如下参数说明displayName画布上展示的名称logoUrlCDN 上的 Logo 地址authors维护者列表description一句话描述auth认证定义可为单个、数组或 undefinedactions/triggersAction / Trigger 实例数组构造函数内部会按键名action.name建立索引categories分类如PieceCategory.PRODUCTIVITYminimumSupportedRelease/maximumSupportedRelease支持的 Activepieces 版本区间低于当前最低版本时会自动抬升Airtable 的 index.ts 是它的完整实战样例其中还展示了createCustomApiCallAction这种免写代码、直接透传自定义 API 调用的快捷 Action。createActioncreateAction()接受name、displayName、description、props、run等参数framework/src/lib/action/action.ts。两点默认行为值得注意未传test时test默认复用run未传errorHandlingOptions时continueOnFailure与retryOnFailure默认值均为false即失败即中断、不自动重试。此外还支持outputSchema、audience、classification、aiMetadata等元数据字段——aiMetadata中的description与idempotent标记会被 AI Agent 用于理解该 Action 的能力与副作用Airtable 的 create-record.ts 已示范。createTriggerTrigger 通过type声明触发策略TriggerStrategy.POLLING轮询、TriggerStrategy.WEBHOOK外部 Webhook、TriggerStrategy.APP_WEBHOOK应用内事件监听。轮询型 Trigger 的推荐写法是借助pollingHelper与DedupeStrategy如TIMEBASED封装test/onEnable/onDisable/run四个钩子样板代码见 new-record.trigger.ts。总结开发一个 Activepieces Piece 的完整路径是用npm run create-piece生成骨架 → 注册tsconfig.base.json路径映射 → 编写auth.ts定义认证 → 在actions/与trigger/下逐个实现能力 → 在index.ts用createPiece装配 → 维护i18n/translation.json。在run()内部context提供了凭据、属性、持久化存储、流式文件、连接管理、流程暂停/响应与 Agent 工具等完整运行时能力遵循Trigger 返回数组、统一走httpClient、提供sampleData、维护 i18n四条规则即可保证 Piece 被引擎正确执行并被画布完整渲染。需要深入阅读的参考实现均在 packages/pieces/community/airtable/ 与 packages/pieces/framework/ 中可按需对照。【免费下载链接】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 SDK 开发指南：从脚手架到运行时上下文的完整实战
Activepieces Piece SDK 开发指南从脚手架到运行时上下文的完整实战【免费下载链接】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/activepiecesActivepieces 是一个开源 AI 工作流自动化平台其 400 集成全部以 Piece积木式能力包的形式存在。本文以仓库内 packages/pieces/CLAUDE.md 为骨架系统讲解如何从零创建一个 Piece包含脚手架命令、工程接入、目录结构、三种认证模式、run()内的完整运行时上下文Piece Context以及必须遵守的编码规则。读完本文你将能够独立为 Activepieces 贡献一个新的社区 Piece或基于 SDK 改造现有集成。快速开始三个脚手架命令Activepieces 通过 package.json 暴露了三个用于生成 Piece 骨架的命令它们底层都调用packages/cli的 TypeScript 入口packages/cli/src/index.tsnpm run create-piece # 创建一个全新的 Piece npm run create-action # 为已有 Piece 添加一个 Action npm run create-trigger # 为已有 Piece 添加一个 Trigger三条命令的实际执行链路分别对应 CLI 子命令pieces create、actions create、triggers create生成代码后即可在packages/pieces/community/{name}/下看到骨架文件。接入 tsconfig 路径映射创建完成后还需要把新 Piece 的入口注册到 tsconfig.base.json 的paths中形如activepieces/piece-{name}: [packages/pieces/community/{name}/src/index.ts]这一步让 TypeScript 能以activepieces/piece-{name}的形式解析新 Piece是 monorepo 内部引用与编译的前提。Piece 目录结构一个标准的社区 Piece 遵循统一的目录约定packages/pieces/community/{name}/ ├── src/index.ts # createPiece() 定义Piece 的入口与装配点 ├── src/lib/auth.ts # 认证配置SecretText / OAuth2 / CustomAuth ├── src/lib/actions/ # 每个 Action 一个文件 ├── src/lib/trigger/ # 每个 Trigger 一个文件 ├── src/lib/common/ # API 辅助函数、共享 props └── src/i18n/translation.json # i18n 翻译文件仓库中 packages/pieces/community/airtable/ 是一个完整范例src/index.ts中通过createPiece()装配了 30 个 Action、2 个 Trigger 和认证对象见 airtable/src/index.tssrc/lib/actions/下每个文件对应一个 Action如 create-record.tssrc/lib/trigger/下是轮询型触发器如 new-record.trigger.tssrc/i18n/下除translation.json外还包含多语言版本zh、ja、fr 等。三种认证模式Auth PatternsSDK 通过PieceAuth提供三种内置认证类型且都支持validate回调用于校验凭据模式适用场景关键点PieceAuth.SecretText()API Key / Token常用validate回调做真实请求校验PieceAuth.OAuth2()标准 OAuth2 授权由平台托管授权流程与令牌刷新PieceAuth.CustomAuth({ props })多字段凭据自定义字段组合如{ username, password }以 Airtable 的 auth.ts 为例SecretText的validate回调直接向目标 API 发一个真实请求来确认令牌有效性export const airtableAuth PieceAuth.SecretText({ displayName: Personal Access Token, required: true, description: ...获取令牌的步骤说明..., validate: async (auth) { try { await httpClient.sendRequest({ method: HttpMethod.GET, url: https://api.airtable.com/v0/meta/bases, authentication: { type: AuthenticationType.BEARER_TOKEN, token: auth.auth, }, }); return { valid: true }; } catch (e) { return { valid: false, error: Invalid personal access token }; } }, });validate返回{ valid: boolean, error?: string }校验通过时用户在画布上能顺利保存连接失败时则携带可读错误信息。三种认证在框架层的类型定义可参见 framework/src/lib/property/authentication/。从源码结构可以推断createPiece()还要求同一 Piece 的多个认证属性传入数组时按类型唯一否则直接抛错Auth properties must be unique by type见 framework/src/lib/piece.ts。Piece Contextrun()内的完整运行时能力Action 与 Trigger 的run(context)接收一个类型化的context对象这是 Piece 与 Activepieces 引擎交互的唯一通道。以下按使用场景逐一说明context.auth— 已解析的凭据运行时经过平台解密、解析后的连接凭据。其具体结构由 Piece 的认证类型推导SecretText得到{ secret_text }OAuth2得到{ access_token, ... }CustomAuth得到自定义字段对象。类型推导逻辑见 framework/src/lib/context/index.ts因此run()内访问context.auth是类型安全的。context.propsValue— 已解析的输入属性用户在画布上为 Action 填写的props经过解析后的值。Airtable 的 create-record.ts 展示了典型用法从context.propsValue取出base、tableId、fields过滤空值后再组装请求。context.store— 跨执行持久化的键值存储用于在多次执行之间保存状态如游标、去重标记context.store.putT(key, value, scope?): PromiseT context.store.getT(key, scope?): PromiseT | null context.store.delete(key, scope?): Promisevoidscope支持StoreScope.PROJECT项目级兼容历史值COLLECTION与StoreScope.FLOW流程级接口定义见 framework/src/lib/context/index.ts。context.files— 文件上传/下载重点context.files.write({ fileName, data })的data既接受Buffer也接受Readable流见FilesService接口 framework/src/lib/context/index.ts。当处理大文件时应把源流例如 S3getObject().Body直接传给write让文件在沙箱内边读边写、不经内存缓冲地流转到对象存储const s3Stream await s3.getObject({ Bucket, Key }).createReadStream(); await context.files.write({ fileName: large.bin, data: s3Stream });与之对应输入侧使用Property.File({ streaming: true })时属性值不再解析为缓冲在内存的ApFile而是ApStreamingFiletype ApStreamingFile { filename: string; extension?: string; size?: number; body: Readable; };类型定义见 framework/src/lib/property/input/file-property.ts。流式场景下需要遵循三条实践优先选择接受未知长度流的目标客户端如 S3lib-storage的Upload、AzureuploadStream、Google Drivemedia.body、SFTPclient.putsize是尽力而为的值对 chunked 编码或Content-Encoding压缩过的源流size会缺失因此只有当目标 API 强制要求Content-Length时才去读取它httpClient不会重试流式 body当请求体是Readable或form-data时retries被强制为0——因为重试循环会重放一个已被消费的流导致发出截断的 body。如果确实需要重试请先把 body 缓冲为Buffer。context.connections— 连接管理运行时管理 OAuth 等连接对象的入口支持按 key 获取连接值ConnectionsManager.get(key)见 framework/src/lib/context/index.ts。context.server— API 访问信息提供token内部 API 令牌、apiUrl、publicUrl三个字段ServerContext见 framework/src/lib/context/index.ts用于调用 Activepieces 自身 API 或拼接回调地址。流程控制stop / pause / respondAPI行为context.run.stop({ response })停止流程直接返回 HTTP 响应context.run.pause({ pauseMetadata })暂停流程等待延时到期或 Webhook 回调后恢复context.run.respond({ response })先发送响应流程继续执行需要说明的是源码中pause自 2026-04-12 起标记为deprecated引擎层面推荐改用context.run.createWaitpoint(...)创建DELAY/WEBHOOK等待点并返回resumeUrl配合context.run.waitForWaitpoint(...)的组合见 framework/src/lib/context/index.ts。新写的 Piece 应优先使用新的 waitpoint 原语。其他上下文能力context.agent.tools()为 AI Agent 构建工具Agent 侧工具注册context.generateResumeUrl()为暂停的流程生成 Webhook 恢复地址同样处于废弃过渡期优先使用 waitpoint 返回的buildResumeUrlcontext.executionTypeBEGIN表示流程初次执行RESUME表示暂停后恢复执行据此可区分分支逻辑ActionContext联合类型见 framework/src/lib/context/index.ts。关键规则Key Rules编写 Piece 时必须遵守以下约定否则无法通过构建、测试或无法被画布正确渲染Trigger 的run()必须返回数组。无论轮询还是 Webhook 触发返回值都必须是元素数组引擎按元素逐条下发。可对照 new-record.trigger.ts 中pollingHelper.poll的返回值使用方式HTTP 请求统一使用activepieces/pieces-common的httpClient。它封装了认证注入、错误处理与限流逻辑禁止直接裸写fetch/axiosAirtable 的 auth.ts 是标准用法示例Trigger 必须提供sampleData。画布上的测试触发器依赖它渲染示例输出缺失会导致测试功能不可用i18n维护src/i18n/translation.json使用与 key 同名的英文值identity mapping作为默认翻译平台据此做多语言展示。源码级理解createPiece/createAction/createTrigger理解三个工厂函数的底层契约能帮你写出更规范的 Piece。createPiececreatePiece()返回Piece实例framework/src/lib/piece.ts其参数契约如下参数说明displayName画布上展示的名称logoUrlCDN 上的 Logo 地址authors维护者列表description一句话描述auth认证定义可为单个、数组或 undefinedactions/triggersAction / Trigger 实例数组构造函数内部会按键名action.name建立索引categories分类如PieceCategory.PRODUCTIVITYminimumSupportedRelease/maximumSupportedRelease支持的 Activepieces 版本区间低于当前最低版本时会自动抬升Airtable 的 index.ts 是它的完整实战样例其中还展示了createCustomApiCallAction这种免写代码、直接透传自定义 API 调用的快捷 Action。createActioncreateAction()接受name、displayName、description、props、run等参数framework/src/lib/action/action.ts。两点默认行为值得注意未传test时test默认复用run未传errorHandlingOptions时continueOnFailure与retryOnFailure默认值均为false即失败即中断、不自动重试。此外还支持outputSchema、audience、classification、aiMetadata等元数据字段——aiMetadata中的description与idempotent标记会被 AI Agent 用于理解该 Action 的能力与副作用Airtable 的 create-record.ts 已示范。createTriggerTrigger 通过type声明触发策略TriggerStrategy.POLLING轮询、TriggerStrategy.WEBHOOK外部 Webhook、TriggerStrategy.APP_WEBHOOK应用内事件监听。轮询型 Trigger 的推荐写法是借助pollingHelper与DedupeStrategy如TIMEBASED封装test/onEnable/onDisable/run四个钩子样板代码见 new-record.trigger.ts。总结开发一个 Activepieces Piece 的完整路径是用npm run create-piece生成骨架 → 注册tsconfig.base.json路径映射 → 编写auth.ts定义认证 → 在actions/与trigger/下逐个实现能力 → 在index.ts用createPiece装配 → 维护i18n/translation.json。在run()内部context提供了凭据、属性、持久化存储、流式文件、连接管理、流程暂停/响应与 Agent 工具等完整运行时能力遵循Trigger 返回数组、统一走httpClient、提供sampleData、维护 i18n四条规则即可保证 Piece 被引擎正确执行并被画布完整渲染。需要深入阅读的参考实现均在 packages/pieces/community/airtable/ 与 packages/pieces/framework/ 中可按需对照。【免费下载链接】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），仅供参考