Activepieces Piece 类型与分类完全指南Location、命名规范与 PieceCategory 详解【免费下载链接】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本篇指南面向所有需要在 Activepieces 中开发或维护 Piece集成组件的开发者系统讲解三种 Piece 存放位置community/、core/、custom/的适用场景、包命名规范、17 个PieceCategory分类值的语义与用法并列出平台内置、禁止重复开发的 Core Pieces 清单。读完本文你将能正确地为任意集成选择存放位置、命名包名、打上准确的分类标签并理解这些元数据在框架层与构建层如何被消费。三种 Piece 位置选对目录是第一步在 Activepieces 仓库中所有 Piece 源码都位于packages/pieces/之下按用途划分为三个子目录。写任何集成代码之前先回答这段集成是给谁用的再决定放哪里LocationUse whenExamplescommunity/第三方集成任何用户都可以使用Slack、Notion、Stripecore/平台内置工具类与应用无关HTTP、Store、Math Helpercustom/针对特定客户的私有 Piece内部 CRM、私有 APIGolden rule除非有明确理由几乎所有工作都放在community/。这条规则在技能文档.agents/skills/piece-builder/SKILL.md的 Step 2 PLAN 阶段被再次强调默认使用packages/pieces/community/只有当用户明确说custom piece时才进入packages/pieces/custom/。从仓库结构看community/下已有上千个第三方集成从 activecampaign 到 zoom而core/只维护约二十余个平台工具custom/目录则基本保持空置仅保留占位说明——这从侧面印证了三种位置的定位差异。包命名规范名字决定构建与注册每种位置对应不同的 npm 包命名格式LocationFormatExamplecommunity/activepieces/piece-nameactivepieces/piece-slackcore/activepieces/piece-nameactivepieces/piece-httpcustom/任意合法的 npm 名称mycompany/piece-crm以 core 的 HTTP 为例packages/pieces/core/http/package.json中name: activepieces/piece-http与community/使用同一套activepieces/piece-name前缀。命名并非只是风格问题它直接参与构建链路Workspace 注册新建 Piece 后必须在仓库根目录的tsconfig.base.json中以字母序插入一条路径映射例如activepieces/piece-name: [packages/pieces/community/name/src/index.ts]否则构建直接失败详见.agents/skills/piece-builder/SKILL.md的 Step 5 WIRING checklist。包名即身份name会成为后续 Piece 安装、版本管理pieceName与 manifest 引用的关键标识因此命名需稳定发布后不可随意更改。PieceCategory17 个分类值与适用场景分类通过PieceCategory枚举表达在源码中定义于packages/core/shared/src/lib/automation/pieces/piece.ts#L49-L67。在业务代码中通过以下方式引入import { PieceCategory } from activepieces/shared;从源码结构看框架侧也通过activepieces/pieces-framework与activepieces/core-piece-types重新导出了该枚举因此社区 Piece 中两种 import 写法均可例如 Slack 的packages/pieces/community/slack/src/index.ts#L7使用activepieces/pieces-framework。完整分类值与用途对照如下CategoryUse forARTIFICIAL_INTELLIGENCEAI/LLM 服务OpenAI、AnthropicCOMMUNICATION聊天、邮件、消息Slack、Gmail、TwilioCOMMERCE电子商务Shopify、WooCommerceACCOUNTING财务/会计QuickBooks、XeroBUSINESS_INTELLIGENCE分析、报表Google AnalyticsCONTENT_AND_FILES文件、文档Google Drive、Notion、DropboxDEVELOPER_TOOLS开发工具GitHub、Jira、LinearCUSTOMER_SUPPORT客服支持Intercom、ZendeskFORMS_AND_SURVEYS表单Typeform、Google FormsHUMAN_RESOURCES人力资源BambooHR、WorkdayMARKETING营销Mailchimp、HubSpot MarketingPAYMENT_PROCESSING支付Stripe、PayPalPRODUCTIVITY通用生产力Trello、AirtableSALES_AND_CRMCRM/销售Salesforce、HubSpot CRMCORE平台工具仅core/的 Piece 使用FLOW_CONTROL流程逻辑仅core/的 Piece 使用UNIVERSAL_AI通用 AI 连接器仅core/的 Piece 使用多类别标注一个 Piece 可以属于多个分类分类是数组允许一个 Piece 同时命中多个领域categories: [PieceCategory.COMMERCE, PieceCategory.PAYMENT_PROCESSING]仓库中 Stripe 正是这种写法的真实示例——packages/pieces/community/stripe/src/index.ts#L161同时标注了COMMERCE与PAYMENT_PROCESSING。多分类有助于用户在 Piece 选择器中按场景更精准地检索到你的集成建议一个 Piece 归属 12 个最贴切的分类即可不必贪多。框架层面的元数据约束从packages/pieces/framework/src/lib/piece-metadata.ts#L24可以看到categories在元数据 schema 中是可选字段z.optional(z.array(z.enum(PieceCategory)))类型为PieceCategory[]packages/pieces/framework/src/lib/piece.ts#L118中Piece类的构造函数同样将其声明为可选数组。也就是说不传categories不会导致构建失败但推荐始终填写因为分类直接驱动 builder 中 Piece 选择器的分组、搜索与展示体验缺失会显著降低集成被发现的可能性。Core Pieces 清单平台内置请勿重复造轮子以下 Piece 由平台内置在packages/pieces/core/中功能与定位明确。写新集成时先核对这张表凡是已经覆盖的能力一律复用不要重复开发同名 Piece参见.agents/skills/piece-builder/piece-types.md与.agents/skills/piece-builder/SKILL.md的 do NOT recreate these 说明PieceWhat it doeshttp通用 HTTP 请求store流程内的键值存储schedule基于 Cron 的定时触发器delay暂停流程执行webhook通用 Webhook 触发器manual-trigger手动触发流程执行data-mapper数据转换/映射math-helper数学运算text-helper字符串操作date-helper日期/时间操作file-helper文件操作approval人工审批步骤smtp通过 SMTP 发送邮件sftpSFTP 文件传输csvCSV 解析/生成pdfPDF 生成qrcode二维码生成tablesActivepieces Tables 集成subflows调用其他流程connections连接管理formsActivepieces Formsgraphql通用 GraphQL 请求crypto密码学工具xmlXML 解析image-helper图像处理这张表与仓库实际目录一一对应——packages/pieces/core/下正是http、store、schedule、delay、webhook、manual-trigger、data-mapper、math-helper、text-helper、date-helper、file-helper、approval、smtp、sftp、csv、pdf、qrcode、tables、subflows、connections、forms、graphql、crypto、xml、image-helper等目录。以http为例packages/pieces/core/http/src/index.ts#L5-L25展示了内置 Core Piece 的典型定义形态import { PieceAuth, createPiece, PieceCategory } from activepieces/pieces-framework; import { httpSendRequestAction } from ./lib/actions/send-http-request-action; import { parseUrl } from ./lib/actions/parse-url; export const http createPiece({ displayName: HTTP, description: Send HTTP requests to any URL and use the response in your flow, logoUrl: https://cdn.activepieces.com/pieces/new-core/http.svg, categories: [PieceCategory.CORE], auth: PieceAuth.None(), minimumSupportedRelease: 0.88.2, actions: [httpSendRequestAction, parseUrl], authors: [bibhuty-did-this, /* ... */], triggers: [], });注意两点核心事实categories: [PieceCategory.CORE]——CORE、FLOW_CONTROL、UNIVERSAL_AI三个分类被明确保留给core/下的平台 Piece 使用。如果你的第三方集成想标注这三个分类从目录定位规则看是不被允许的应选用面向业务的 14 个分类之一。minimumSupportedRelease字段标注了该 Piece 要求的最低平台版本社区 Piece 同样需要设置用于保证运行时兼容性。深入Piece 的类型系统与分发PieceCategory并不是唯一的分类维度。在packages/core/shared/src/lib/automation/pieces/piece.ts中与分类并列的还有两个关键枚举PieceTypeCUSTOM|OFFICIAL——区分官方 Piece 与自定义 PiecePackageTypeARCHIVE|REGISTRY——区分以归档包分发还是从 npm Registry 分发。它们与前面的三种目录定位对应关系可以概括为目录PieceType分发方式典型场景community/官方随平台发布Registry 包面向全体用户的第三方集成core/官方内置平台通用工具custom/CUSTOMArchive 或自定义 Registry 包需绑定platformId单客户私有集成源码中PrivatePiecePackage、OfficialPiecePackage、CustomNpmPiecePackage三个 zod schemapiece.ts#L13-L47分别描述了私有归档包、官方 Registry 包与自定义 Registry 包的元数据形态——其中自定义包额外携带platformId用于把私有 Piece 绑定到特定平台租户这与custom/目录面向特定客户的定位完全吻合。实战速查新建 Piece 时的四步决策把上文浓缩成新建集成时的决策链选位置第三方集成 →packages/pieces/community/name/平台工具 →packages/pieces/core/name/先确认不在 Core Pieces 清单中客户私有 →packages/pieces/custom/name/且包名使用自定义 npm 命名空间。定包名community/与core/统一为activepieces/piece-namecustom/使用任意合法 npm 名如mycompany/piece-crm。打分类在createPiece({ ... })的categories字段中填写 12 个最贴切的PieceCategory值CORE/FLOW_CONTROL/UNIVERSAL_AI仅供 core Piece 使用。注册构建在仓库根目录 tsconfig.base.json 中按字母序登记路径映射然后执行npx turbo run build --filteractivepieces/piece-name与npx turbo run lint --filteractivepieces/piece-name验证通过。完成目录与分类决策后可继续阅读同目录下的其他技能文档深入开发脚手架与配置文件见 new-piece-scaffold.md认证模式见 auth-patterns.mdAction/Trigger 编写范式见 action-patterns.md 与 trigger-patterns.mdAI 元数据标注见 ai-metadata.md。【免费下载链接】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 类型与分类完全指南：Location、命名规范与 PieceCategory 详解
Activepieces Piece 类型与分类完全指南Location、命名规范与 PieceCategory 详解【免费下载链接】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本篇指南面向所有需要在 Activepieces 中开发或维护 Piece集成组件的开发者系统讲解三种 Piece 存放位置community/、core/、custom/的适用场景、包命名规范、17 个PieceCategory分类值的语义与用法并列出平台内置、禁止重复开发的 Core Pieces 清单。读完本文你将能正确地为任意集成选择存放位置、命名包名、打上准确的分类标签并理解这些元数据在框架层与构建层如何被消费。三种 Piece 位置选对目录是第一步在 Activepieces 仓库中所有 Piece 源码都位于packages/pieces/之下按用途划分为三个子目录。写任何集成代码之前先回答这段集成是给谁用的再决定放哪里LocationUse whenExamplescommunity/第三方集成任何用户都可以使用Slack、Notion、Stripecore/平台内置工具类与应用无关HTTP、Store、Math Helpercustom/针对特定客户的私有 Piece内部 CRM、私有 APIGolden rule除非有明确理由几乎所有工作都放在community/。这条规则在技能文档.agents/skills/piece-builder/SKILL.md的 Step 2 PLAN 阶段被再次强调默认使用packages/pieces/community/只有当用户明确说custom piece时才进入packages/pieces/custom/。从仓库结构看community/下已有上千个第三方集成从 activecampaign 到 zoom而core/只维护约二十余个平台工具custom/目录则基本保持空置仅保留占位说明——这从侧面印证了三种位置的定位差异。包命名规范名字决定构建与注册每种位置对应不同的 npm 包命名格式LocationFormatExamplecommunity/activepieces/piece-nameactivepieces/piece-slackcore/activepieces/piece-nameactivepieces/piece-httpcustom/任意合法的 npm 名称mycompany/piece-crm以 core 的 HTTP 为例packages/pieces/core/http/package.json中name: activepieces/piece-http与community/使用同一套activepieces/piece-name前缀。命名并非只是风格问题它直接参与构建链路Workspace 注册新建 Piece 后必须在仓库根目录的tsconfig.base.json中以字母序插入一条路径映射例如activepieces/piece-name: [packages/pieces/community/name/src/index.ts]否则构建直接失败详见.agents/skills/piece-builder/SKILL.md的 Step 5 WIRING checklist。包名即身份name会成为后续 Piece 安装、版本管理pieceName与 manifest 引用的关键标识因此命名需稳定发布后不可随意更改。PieceCategory17 个分类值与适用场景分类通过PieceCategory枚举表达在源码中定义于packages/core/shared/src/lib/automation/pieces/piece.ts#L49-L67。在业务代码中通过以下方式引入import { PieceCategory } from activepieces/shared;从源码结构看框架侧也通过activepieces/pieces-framework与activepieces/core-piece-types重新导出了该枚举因此社区 Piece 中两种 import 写法均可例如 Slack 的packages/pieces/community/slack/src/index.ts#L7使用activepieces/pieces-framework。完整分类值与用途对照如下CategoryUse forARTIFICIAL_INTELLIGENCEAI/LLM 服务OpenAI、AnthropicCOMMUNICATION聊天、邮件、消息Slack、Gmail、TwilioCOMMERCE电子商务Shopify、WooCommerceACCOUNTING财务/会计QuickBooks、XeroBUSINESS_INTELLIGENCE分析、报表Google AnalyticsCONTENT_AND_FILES文件、文档Google Drive、Notion、DropboxDEVELOPER_TOOLS开发工具GitHub、Jira、LinearCUSTOMER_SUPPORT客服支持Intercom、ZendeskFORMS_AND_SURVEYS表单Typeform、Google FormsHUMAN_RESOURCES人力资源BambooHR、WorkdayMARKETING营销Mailchimp、HubSpot MarketingPAYMENT_PROCESSING支付Stripe、PayPalPRODUCTIVITY通用生产力Trello、AirtableSALES_AND_CRMCRM/销售Salesforce、HubSpot CRMCORE平台工具仅core/的 Piece 使用FLOW_CONTROL流程逻辑仅core/的 Piece 使用UNIVERSAL_AI通用 AI 连接器仅core/的 Piece 使用多类别标注一个 Piece 可以属于多个分类分类是数组允许一个 Piece 同时命中多个领域categories: [PieceCategory.COMMERCE, PieceCategory.PAYMENT_PROCESSING]仓库中 Stripe 正是这种写法的真实示例——packages/pieces/community/stripe/src/index.ts#L161同时标注了COMMERCE与PAYMENT_PROCESSING。多分类有助于用户在 Piece 选择器中按场景更精准地检索到你的集成建议一个 Piece 归属 12 个最贴切的分类即可不必贪多。框架层面的元数据约束从packages/pieces/framework/src/lib/piece-metadata.ts#L24可以看到categories在元数据 schema 中是可选字段z.optional(z.array(z.enum(PieceCategory)))类型为PieceCategory[]packages/pieces/framework/src/lib/piece.ts#L118中Piece类的构造函数同样将其声明为可选数组。也就是说不传categories不会导致构建失败但推荐始终填写因为分类直接驱动 builder 中 Piece 选择器的分组、搜索与展示体验缺失会显著降低集成被发现的可能性。Core Pieces 清单平台内置请勿重复造轮子以下 Piece 由平台内置在packages/pieces/core/中功能与定位明确。写新集成时先核对这张表凡是已经覆盖的能力一律复用不要重复开发同名 Piece参见.agents/skills/piece-builder/piece-types.md与.agents/skills/piece-builder/SKILL.md的 do NOT recreate these 说明PieceWhat it doeshttp通用 HTTP 请求store流程内的键值存储schedule基于 Cron 的定时触发器delay暂停流程执行webhook通用 Webhook 触发器manual-trigger手动触发流程执行data-mapper数据转换/映射math-helper数学运算text-helper字符串操作date-helper日期/时间操作file-helper文件操作approval人工审批步骤smtp通过 SMTP 发送邮件sftpSFTP 文件传输csvCSV 解析/生成pdfPDF 生成qrcode二维码生成tablesActivepieces Tables 集成subflows调用其他流程connections连接管理formsActivepieces Formsgraphql通用 GraphQL 请求crypto密码学工具xmlXML 解析image-helper图像处理这张表与仓库实际目录一一对应——packages/pieces/core/下正是http、store、schedule、delay、webhook、manual-trigger、data-mapper、math-helper、text-helper、date-helper、file-helper、approval、smtp、sftp、csv、pdf、qrcode、tables、subflows、connections、forms、graphql、crypto、xml、image-helper等目录。以http为例packages/pieces/core/http/src/index.ts#L5-L25展示了内置 Core Piece 的典型定义形态import { PieceAuth, createPiece, PieceCategory } from activepieces/pieces-framework; import { httpSendRequestAction } from ./lib/actions/send-http-request-action; import { parseUrl } from ./lib/actions/parse-url; export const http createPiece({ displayName: HTTP, description: Send HTTP requests to any URL and use the response in your flow, logoUrl: https://cdn.activepieces.com/pieces/new-core/http.svg, categories: [PieceCategory.CORE], auth: PieceAuth.None(), minimumSupportedRelease: 0.88.2, actions: [httpSendRequestAction, parseUrl], authors: [bibhuty-did-this, /* ... */], triggers: [], });注意两点核心事实categories: [PieceCategory.CORE]——CORE、FLOW_CONTROL、UNIVERSAL_AI三个分类被明确保留给core/下的平台 Piece 使用。如果你的第三方集成想标注这三个分类从目录定位规则看是不被允许的应选用面向业务的 14 个分类之一。minimumSupportedRelease字段标注了该 Piece 要求的最低平台版本社区 Piece 同样需要设置用于保证运行时兼容性。深入Piece 的类型系统与分发PieceCategory并不是唯一的分类维度。在packages/core/shared/src/lib/automation/pieces/piece.ts中与分类并列的还有两个关键枚举PieceTypeCUSTOM|OFFICIAL——区分官方 Piece 与自定义 PiecePackageTypeARCHIVE|REGISTRY——区分以归档包分发还是从 npm Registry 分发。它们与前面的三种目录定位对应关系可以概括为目录PieceType分发方式典型场景community/官方随平台发布Registry 包面向全体用户的第三方集成core/官方内置平台通用工具custom/CUSTOMArchive 或自定义 Registry 包需绑定platformId单客户私有集成源码中PrivatePiecePackage、OfficialPiecePackage、CustomNpmPiecePackage三个 zod schemapiece.ts#L13-L47分别描述了私有归档包、官方 Registry 包与自定义 Registry 包的元数据形态——其中自定义包额外携带platformId用于把私有 Piece 绑定到特定平台租户这与custom/目录面向特定客户的定位完全吻合。实战速查新建 Piece 时的四步决策把上文浓缩成新建集成时的决策链选位置第三方集成 →packages/pieces/community/name/平台工具 →packages/pieces/core/name/先确认不在 Core Pieces 清单中客户私有 →packages/pieces/custom/name/且包名使用自定义 npm 命名空间。定包名community/与core/统一为activepieces/piece-namecustom/使用任意合法 npm 名如mycompany/piece-crm。打分类在createPiece({ ... })的categories字段中填写 12 个最贴切的PieceCategory值CORE/FLOW_CONTROL/UNIVERSAL_AI仅供 core Piece 使用。注册构建在仓库根目录 tsconfig.base.json 中按字母序登记路径映射然后执行npx turbo run build --filteractivepieces/piece-name与npx turbo run lint --filteractivepieces/piece-name验证通过。完成目录与分类决策后可继续阅读同目录下的其他技能文档深入开发脚手架与配置文件见 new-piece-scaffold.md认证模式见 auth-patterns.mdAction/Trigger 编写范式见 action-patterns.md 与 trigger-patterns.mdAI 元数据标注见 ai-metadata.md。【免费下载链接】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），仅供参考
