Activepieces Shared 包开发指南activepieces/shared 的模型模式、公共工具与枚举扩展规范【免费下载链接】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/shared 是 Activepieces 全仓库server、engine、worker、web、pieces共享的类型与运行时校验中枢承载 Types、DTO、Zod schema 与公共工具函数。本文以仓库中的 packages/core/shared/CLAUDE.md 为骨架逐条展开其模型模式、工具函数清单、关键枚举与导出规则并结合packages/core/utils、packages/core/execution等源码给出可验证的实现细节与如何新增枚举的完整操作路径。读完本文你将掌握在该仓库中新增共享模型、权限、错误码、特性标志与审计事件的正确姿势并理解每次改动为何必须提升包版本号。一、包定位与版本管理铁律该文档开门见山地定义了包的边界内容范围Types类型、DTO数据传输对象、Zod schemas运行时校验模式、utilities工具函数。版本约束任何变更都必须提升版本号——修复类改动 bump patch新增导出 bump minor。这是硬性要求因为该包被 server / engine / worker / web / pieces 数百个包共同依赖任何未 bump 的破坏性改动都会在 monorepo 依赖图里静默传播。从仓库结构看activepieces/shared的源码位于 packages/core/shared/src按业务域划分为lib/automation流程、连接、变量、表格、MCP、Webhook 等、lib/core认证、标志、文件、用户等、lib/ee企业版审计事件、SSO、SCIM、计费等、lib/management平台、项目、模板等。值得注意的一个实现事实shared并非把所有代码都写在本地目录里。其入口 packages/core/shared/src/index.ts 第 23 行和第 37 行分别通过export * from activepieces/core-utils与export * from activepieces/core-execution整体转发了另外两个核心包的全部导出面。从源码注释可以推断这是为了兼容历史导入路径注释提及 SRE-163flows / flow-run / engine / agents / workers 已被抽离到activepieces/core-execution。因此新增共享能力时若能力属于工具函数层应落在core-utils若属于执行/流程层应落在core-executionshared仅负责聚合与转发。二、模型模式Zod schema z.infer 双导出文档给出的模型模式是一条贯穿全仓库的约定Zod schema z.infer双导出。使用BaseModelSchemaid, created, updated、Nullable()、NullableEnum()。参考src/lib/automation/下任意文件。其含义是每个模型文件同时导出两部分——一个 Zod schema 对象用于运行时校验、OpenAPI 文档生成、前后端边界校验以及用z.infer推导出的 TypeScript 类型用于编译期静态检查。这样一份定义同时服务运行时与编译期避免类型与校验逻辑双份维护产生漂移。2.1 BaseModelSchema所有模型的地基packages/core/utils/src/lib/base-model.ts 是这一模式的源头实现import * as z from zod/mini export type BaseModelT { id: T created: string updated: string } export const DateOrString z.pipe( z.transform((val) (val instanceof Date ? val.toISOString() : val)), z.string(), ) export const BaseModelSchema { id: z.string(), created: DateOrString, updated: DateOrString, }关键点解读BaseModelSchema不是用z.object()包起来的一个完整 schema而是一个字段形状实际使用时通过z.object({ ...BaseModelSchema, ...扩展字段 })展开继承。这解释了为什么文档强调使用BaseModelSchema而非继承某个类。DateOrString使用z.pipe把Date实例归一化为 ISO 字符串保证序列化一致性。Nullable与NullableEnum是对 Zod 可空类型的封装Nullable(schema)等价于z.optional(z.nullable(schema))NullableEnum(enumObj)用于可空枚举字段目的是生成合法的 OpenAPI Schemaz.nullable在 OpenAPI 中输出type: [T, null]。2.2 一个仿照仓库惯例的模型示例以src/lib/automation/下文件的写法为参照新增一个模型的标准形态如下import { z } from zod import { BaseModelSchema, Nullable, NullableEnum } from activepieces/shared export type ExampleId string // 1) 定义枚举 export enum ExampleStatus { DRAFT DRAFT, ACTIVE ACTIVE, } // 2) 定义 Zod schema继承 BaseModelSchema 并叠加业务字段 export const ExampleSchema z.object({ ...BaseModelSchema, // id / created / updated name: z.string(), status: NullableEnum(ExampleStatus), // 可空枚举 description: Nullable(z.string()), // 可空字符串 tags: z.array(z.string()).optional(), }) // 3) 用 z.infer 推导静态类型并导出 export type Example z.infertypeof ExampleSchema这样ExampleSchema可被服务端用于请求体校验、被 OpenAPI 生成器消费Example类型可被前后端直接 import二者永远保持同步。三、核心公共工具函数速查文档在Key Utilities一节列出src/lib/core/common/下的工具函数清单。从当前仓库源码看这批工具的实际实现位于 packages/core/utils/src/lib/utils.ts、packages/core/utils/src/lib/try-catch.ts、packages/core/utils/src/lib/activepieces-error.ts 等文件并通过activepieces/core-utils统一转发。逐个说明其语义与典型用法3.1 标识符与判空apId()生成 Activepieces 全局唯一 ID 的工厂函数ApId类型定义于core-utils的id-generator所有模型的主键都应经由它产生。isNil(value)判断null或undefined同时作为类型守卫value is null | undefined在过滤可选值时可直接收窄类型。isEmpty(value)空值宽泛判定——null/undefined、空字符串、空数组、空对象均返回true。3.2 异常捕获tryCatch与tryCatchSync的实现位于 packages/core/utils/src/lib/try-catch.ts它们不再抛出异常而是返回一个可判别联合discriminated union结果type ResultT, E Error | { data: T; error: null } | { data: null; error: E } export async function tryCatchT, E Error( fn: () PromiseT, ): PromiseResultT, E用法const { data, error } await tryCatch(() fetchSomething())随后用if (error)或if (data)分支处理避免 try/catch 包裹业务主流程代码路径更清晰。3.3 对象操作spreadIfDefined(obj, key, value)/spreadIfNotUndefined(...)仅在值为非undefined时把字段展开进对象常用于有配置才覆盖默认值的合并场景。omit(obj, keys)剔除指定键返回新对象用于从 DTO 中剥离敏感字段。deepMergeAndCast(target, source)基于 deepmerge 的深合并数组会拼接而非覆盖源码注释明确x [1, 2]与y [3, 4]合并得到[1, 2, 3, 4]用于流版本、配置的增量合并。sanitizeObjectForPostgresql()清洗对象使其可安全写入 PostgreSQL例如把非法键、复杂对象规整为可存储形态位于core-utils的 PostgreSQL 适配层。applyFunctionToValues()对对象所有叶子值应用给定函数典型用于模板递归渲染。3.4 数组与集合chunk(array, size)按固定大小切块用于批量写入、分批拉取等场景源码在 utils.ts 第 154 行起。partition(array, predicate)按谓词把数组拆成[truthy[], falsy[]]两段。unique(array)基于JSON.stringify去重可处理对象数组。SeekPageT分页响应通用容器REST 列表接口统一返回{ data: T[]; next: string | null }形态定义于core-utils的seek-page.ts。formErrors把 Zod 校验错误转换为前端可消费的表单错误结构lib/form-errors.ts相关入口注释说明其仅供 shared 内部相对导入使用。3.5 字符串与格式化kebabCase(str)camelCase / 空格 / 下划线统一转kebab-case实现见 utils.ts 第 81 行先处理 camelCase 边界、替换空格与下划线、再去除首尾连字符。camelCase(str)把snake_case/kebab-case转换为 camelCase。debounce(fn, wait)防抖封装支持按key分组同一 key 的连续调用共享同一计时器用于前端搜索输入等高频场景。这些工具被 server 的 service 层、engine 的执行层与 web 前端广泛复用是一份实现、处处引用的典型代表。四、关键枚举与新增入口文档给出了一张往哪里加新条目的枚举地图。以下逐个说明其定义位置、当前规模与扩展时的配套动作。需要说明文档中记录的枚举条目数量与当前仓库源码可能存在小幅出入仓库持续演进以下以当前源码为准并同时给出文档口径。4.1 Permission权限点定义于 packages/core/utils/src/lib/permission.ts当前源码定义了 30 个权限值文档记录为 26 个export enum Permission { READ_APP_CONNECTION READ_APP_CONNECTION, WRITE_APP_CONNECTION WRITE_APP_CONNECTION, READ_FLOW READ_FLOW, WRITE_FLOW WRITE_FLOW, UPDATE_FLOW_STATUS UPDATE_FLOW_STATUS, WRITE_INVITATION WRITE_INVITATION, READ_INVITATION READ_INVITATION, READ_PROJECT_MEMBER READ_PROJECT_MEMBER, WRITE_PROJECT_MEMBER WRITE_PROJECT_MEMBER, WRITE_PROJECT_RELEASE WRITE_PROJECT_RELEASE, READ_PROJECT_RELEASE READ_PROJECT_RELEASE, READ_RUN READ_RUN, WRITE_RUN WRITE_RUN, READ_FOLDER READ_FOLDER, WRITE_FOLDER WRITE_FOLDER, WRITE_ALERT WRITE_ALERT, READ_ALERT READ_ALERT, READ_MCP READ_MCP, WRITE_MCP WRITE_MCP, WRITE_PROJECT WRITE_PROJECT, READ_PROJECT READ_PROJECT, READ_TABLE READ_TABLE, WRITE_TABLE WRITE_TABLE, READ_KNOWLEDGE_BASE READ_KNOWLEDGE_BASE, WRITE_KNOWLEDGE_BASE WRITE_KNOWLEDGE_BASE, READ_VARIABLE READ_VARIABLE, WRITE_VARIABLE WRITE_VARIABLE, READ_AGENT READ_AGENT, WRITE_AGENT WRITE_AGENT, PUBLISH_SENSITIVE_FLOW_ACCESS PUBLISH_SENSITIVE_FLOW_ACCESS, }新增规则为新功能添加 READ/WRITE 权限对同时要在 server 的access-control-list.ts权限与角色关联表源码注释明确指向该文件中登记并重启主服务使改动生效。同文件还定义了RoleTypeDEFAULT / CUSTOM、PlatformUsageMetric与AIProviderName等关联枚举。4.2 ErrorCode错误码定义于 packages/core/utils/src/lib/activepieces-error.ts 第 527 行起文档记录为 66 个错误码当前源码已进一步扩充。与其配套的是ActivepiecesError类export class ActivepiecesError extends Error { constructor(public error: ApErrorParams, message?: string) { super(error.code (message ? : ${message} : )) } override toString(): string { return JSON.stringify({ code: this.error.code, message: this.message, params: this.error.params }) } }ApErrorParams是一个覆盖 40 余种错误场景的可判别联合认证失败、权限拒绝、实体未找到、配额超限、校验失败、文件过大等每种错误携带自己的结构化params。新增规则在ErrorCode中追加新枚举值后还必须在 server 的error-handler.ts中补充该错误码到 HTTP 状态码的映射否则错误无法以正确的 HTTP 语义返回给客户端。4.3 ApFlagId特性标志定义于 packages/core/shared/src/lib/core/flag/flag.ts文档记录为 42 个特性标志当前源码已包含 46 个覆盖运行环境、认证、存储、限流、前端配置等维度例如环境与版本CURRENT_VERSION、EDITIONce/ee/cloud、ENVIRONMENT、PUBLIC_URL认证EMAIL_AUTH_ENABLED、EMAIL_CODE_AUTH_ENABLED、CLOUD_AUTH_ENABLED、THIRD_PARTY_AUTH_PROVIDERS_TO_SHOW_MAP、SAML_AUTH_ACS_URL执行限制FLOW_RUN_MEMORY_LIMIT_KB、FLOW_RUN_LOG_SIZE_LIMIT_MB、FLOW_RUN_TIME_SECONDS、TRIGGER_TIMEOUT_SECONDS、WEBHOOK_TIMEOUT_SECONDS、PAUSED_FLOW_TIMEOUT_DAYS、EXECUTION_DATA_RETENTION_DAYS平台能力PGVECTOR_AVAILABLE、TOOL_SEARCH_ENABLED、ALLOW_NPM_PACKAGES_IN_CODE_STEP、PROJECT_RATE_LIMITER_ENABLED、DEFAULT_CONCURRENT_JOBS_LIMIT、SMTP_CONFIGURED、TURNSTILE_SITE_KEY前端开关SHOW_COMMUNITY、SHOW_ALERTS、SHOW_PROJECT_MEMBERS、ALLOWED_EMBED_ORIGINS、THEME、TEMPLATES_CATEGORIES同文件还定义了ApEnvironmentprod/dev/test与ApEditionce/ee/cloudFlag模型由{ value: unknown }与BaseModelFlagId组合而成——这正是第二节模型模式的实际应用。4.4 FlowOperationType流程修改操作定义于 packages/core/execution/src/lib/flows/operations/index.ts 第 28 行文档记录为 26 种流程修改操作含LOCK_AND_PUBLISH、CHANGE_STATUS、LOCK_FLOW等。新增规则新增操作类型后必须在 flow service 中补充对应的处理器handler否则该操作在服务端无法被消费。4.5 FlowActionType动作类型定义于 packages/core/execution/src/lib/flows/actions/action.ts 第 7 行是封闭集合仅 4 个值export enum FlowActionType { CODE CODE, PIECE PIECE, LOOP_ON_ITEMS LOOP_ON_ITEMS, ROUTER ROUTER, }4.6 FlowRunStatus运行状态定义于 packages/core/execution/src/lib/flow-run/execution/flow-execution.ts 第 5 行文档记录为 12 个状态QUEUED、RUNNING、SUCCEEDED、FAILED、PAUSED、TIMEOUT、CANCELED等另含QUOTA_EXCEEDED、INTERNAL_ERROR等衍生终态。该枚举驱动运行记录表的状态机与前端运行详情页的展示逻辑。4.7 BranchOperator路由器条件操作符同样定义于 packages/core/execution/src/lib/flows/actions/action.ts 第 113 行起文档记录为 24 个条件操作符覆盖文本TEXT_CONTAINS、TEXT_DOES_NOT_CONTAIN、TEXT_EXACTLY_MATCHES等、数值、日期、布尔等类型的比较语义供 ROUTER 分支节点在 engine 中求值。4.8 WorkerJobTypeWorker 任务类型定义于 packages/core/execution/src/lib/workers/job-data.ts 第 75 行文档记录为 9 种任务类型已见的有RENEW_WEBHOOK、EXECUTE_POLLING、EXECUTE_WEBHOOK等。新增规则新增任务类型后必须在 worker 侧实现对应的任务处理分支否则队列中的新任务无人消费。4.9 ApplicationEventName审计事件定义于 packages/core/shared/src/lib/ee/audit-events/index.ts 第 21 行文档记录为 19 个审计事件采用flow.created、flow.updated、flow.deleted这类资源.动作的点号命名。新增规则为新的可审计动作添加事件名保证操作可被 audit-logs 链路追踪。同目录还提供mock-event-builder.ts便于测试中构造事件样本。4.10 枚举扩展速查表枚举定义文件当前规模新增时的配套动作Permissionpermission.ts30 个权限补 READ/WRITE 对登记到 serveraccess-control-list.ts并重启主服务ErrorCodeactivepieces-error.ts60 余个文档记录 66同步 servererror-handler.ts的 HTTP 映射ApFlagIdflag.ts46 个文档记录 42无需额外动作但需保证 flag 有默认值来源FlowOperationTypeoperations/index.ts26 种在 flow service 增加对应 handlerFlowActionTypeactions/action.ts4 种封闭集合改动需同步 engine 执行器FlowRunStatusflow-execution.ts12 种改动需同步运行状态机与前端展示BranchOperatoractions/action.ts24 种改动需同步 engine 条件求值WorkerJobTypejob-data.ts9 种在 worker 增加任务处理分支ApplicationEventNameaudit-events/index.ts19 个当前源码已扩充新增可审计动作时添加事件名五、导出规则feature barrel 到根入口文档的最后一条约定Export from feature barrel → re-export fromsrc/index.ts.即两条层级每个业务域目录内的index.tsfeature barrel负责聚合该域全部导出而包的根入口 packages/core/shared/src/index.ts 再统一 re-export 所有 feature barrel。这样的好处是使用者只需import { X } from activepieces/shared无需关心内部目录结构树形依赖清晰避免跨目录深引用与core-utils、core-execution的整体转发配合形成单一对外门面。从 src/index.ts 可以看到分区块组织的 re-exportcore认证、标志、文件、用户、management平台、项目、邀请、automation连接、变量、pieces、webhook、trigger、forms、mcp、tables、websocket、eebilling、审计、git-repo、api-key、SCIM、secret-managers 等。新增任何共享模型或枚举都要保证最终出现在这个根入口里否则对包外不可见。六、实战为一项新功能扩展 shared 包假设要为通知渠道功能新增模型、权限与审计事件完整的操作路径如下定义模型在packages/core/shared/src/lib/automation/下新建目录notification-channel/按第二节的模式写出NotificationChannelSchema继承BaseModelSchema、使用Nullable/NullableEnum与NotificationChannel z.infertypeof NotificationChannelSchema。新增枚举如需状态枚举如DRAFT/ACTIVE放在模型文件内如需权限点在 permission.ts 追加READ_NOTIFICATION_CHANNEL/WRITE_NOTIFICATION_CHANNEL并在 server 的access-control-list.ts登记如需审计事件在 audit-events/index.ts 追加NOTIFICATION_CHANNEL_CREATED等事件名如需错误码在 activepieces-error.ts 追加并同步 servererror-handler.ts。建立 feature barrel在notification-channel/下建index.tsexport * from ./notification-channel等。接入根入口在 packages/core/shared/src/index.ts 增加export * from ./lib/automation/notification-channel。升级版本号依据改动性质 bump patch纯修复或 minor新增导出并在依赖该包的各包中同步更新版本引用。验证跑 shared 包的单测与类型检查确认前后端 import 路径均从activepieces/shared解析。七、继续深入包内全部源码packages/core/shared/src工具函数实现packages/core/utils/src/lib/utils.ts、try-catch.ts、base-model.ts错误体系activepieces-error.ts执行层枚举流程操作、动作类型、运行状态、Worker 任务packages/core/execution/src/lib/flows、packages/core/execution/src/lib/workers/job-data.ts模型模式实例src/lib/automation/下的 app-connection、variable、table 等目录总而言之activepieces/shared是整个 Activepieces 代码库的公共契约层模型模式保证前后端类型与校验不漂移工具函数沉淀跨模块复用逻辑枚举地图指明每个扩展点的落位与配套动作导出规则维持单一对外门面。在贡献代码时遵循这份规范即可让新功能以最小摩擦接入现有体系。【免费下载链接】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），仅供参考