Activepieces core 包架构：@activepieces/core-* 依赖边界与模块分层设计

Activepieces core 包架构activepieces/core-* 依赖边界与模块分层设计【免费下载链接】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 仓库中packages/core/目录下核心包的设计规范命名规则、依赖边界thin/thick 分层、以及pieces 与 engine 可依赖 core-*、但严禁依赖activepieces/shared这一关键约束。通过阅读本文你将理解 Activepieces 如何将跨切面库代码组织为框架无关、可打包bundleable的基础库以及activepieces/pieces-framework如何在其中承担符号再导出的桥梁职责。该规范在仓库中由 .claude/rules/core-packages.md 强制约束是参与 Activepieces 核心代码开发、新增 core 包或排查依赖循环时必须遵循的架构底线。一、命名规则packages/core/name与activepieces/core-namepackages/core/目录下的每个包在 npm workspace 中统一命名为activepieces/core-name。以 packages/core/utils 为例目录packages/core/utils包名activepieces/core-utils当前版本 0.6.2构建产物入口./dist/src/index.jsCJS 构建type: commonjs同理packages/core/piece-types→activepieces/core-piece-types、packages/core/formula→activepieces/core-formula、packages/core/execution→activepieces/core-execution在各自的 package.json 中均有对应体现。这一命名并非随意设计统一的core-前缀让所有基础库在一众 workspace 包中一眼可辨也便于构建脚本与 lint 规则对thin 成员做批量校验——例如检查它们是否违反了禁止依赖activepieces/shared、activepieces/server-*、piece 包与 web/React 包的约束。二、唯一例外activepieces/shared是厚thick成员packages/core/shared是目录中唯一的例外它保留原名activepieces/shared而非core-shared这一点在 packages/core/shared/package.json 中可见{ name: activepieces/shared, version: 0.162.0, type: commonjs, sideEffects: false, dependencies: { activepieces/core-execution: workspace:*, activepieces/core-formula: workspace:*, activepieces/core-piece-types: workspace:*, activepieces/core-utils: workspace:*, dayjs: 1.11.9, expr-eval: 2.0.2, socket.io-client: 4.8.1, ... } }它是该目录中唯一厚、应用级thick, app-level的成员具有三个显著特征携带重依赖dayjs日期处理、expr-eval公式表达式求值、socket.io-clientWebSocket 客户端等重量级第三方依赖都沉淀在这里承载 DB/EE/管理面 schema从其 src 目录结构 可以看出它同时包含lib/automation/app-connection、pieces、tables、webhook、websocket 等自动化领域模型、lib/core/authentication、file、flag、user 等平台核心模型、lib/ee/agent、alerts、billing、scim、secret-managers 等企业版功能模型以及lib/management/platform、project、template 等管理面模型——大量领域实体与 DTO 都在此定义依赖方向反转它依赖目录内的 thin 成员core-utils、core-piece-types、core-formula、core-execution而不是反过来。这一点直接体现在其dependencies字段中的四个workspace:*引用上。2.1 目录内顺序thin → thick整个packages/core/目录按从薄到厚thin → thick组织所有跨切面库代码packages/core/utils → activepieces/core-utils 最薄 packages/core/piece-types → activepieces/core-piece-types packages/core/formula → activepieces/core-formula packages/core/execution → activepieces/core-execution 薄、可打包 packages/core/shared → activepieces/shared 最厚唯一 thick 成员从依赖关系看这一顺序也是拓扑有序的core-utils 只依赖deepmerge-ts、ipaddr.js、nanoid、zod等纯工具库不依赖任何兄弟 core 包core-piece-types 依赖core-utilscore-execution 依赖core-utils与core-piece-types并直接使用dayjs、semver、socket.io-client、zodcore-formula 仅依赖dayjs、expr-eval保持独立shared 依赖上述全部四个 thin 成员。该依赖图必须保持无环acyclic这是防止打包膨胀与循环引用的硬性要求。三、thin 成员框架无关的薄基础库thin 成员core-utils、core-piece-types、core-formula、core-execution被定义为框架无关framework-agnostic的基础库其约束非常严格它们严禁import 自activepieces/shared、activepieces/server-*server 侧任何包、任何 piece 包或任何 web/React 包。3.1 薄成员到底薄在哪薄并非指代码量少而是指依赖面窄、领域职责单一。以 core-utils 的 src 结构 为例它只提供纯工具与基础设施错误与断言activepieces-error.ts、assertions.ts、form-errors.ts、friendly-piece-error.ts、try-catch.ts通用工具id-generator.tsnanoid 生成 ID、object-utils.ts、mustache-utils.ts、color.ts、locale.ts安全与网络ssrf-ip-classifier.tsSSRF 防护的 IP 分类缓存与分页byte-lru-cache.ts、seek-page.tsSeekPage分页模型被 framework 与 server 广泛复用领域辅助模型connection-template.ts、permission.ts、project-role.ts、multipart-file.ts同样core-piece-types 的 src 聚焦于类型契约层piece.ts、engine.ts、execution.ts、flows.ts、triggers.ts、forms.ts、tables.ts、mcp-piece.ts等只定义类型与轻量校验逻辑不包含任何应用实现core-formula 的 src 则只包含公式求值的四个文件formula-evaluator.ts、function-implementations.ts、function-registry.ts、function-type-checker.ts是对expr-eval的封装层。3.2 双格式产物与 sideEffectsthin 成员以双格式dual-format发布——同时输出 CJS 与 ESM 构建并声明sideEffects: false以便打包器bundler对未使用的导出做 tree-shaking。这一点在 core-utils 的 package.json 中可见端倪main: ./dist/src/index.js、typings: ./dist/src/index.d.tsCJS 产物而其 tsconfig.json 使用module: esnext、moduleResolution: bundler面向 ESM 生态tsconfig.lib.json 则用module: commonjs产出 CJS。sideEffects: false的语义是该模块的所有导入/导出均为纯代码不附带全局副作用如注册全局对象、修改原型等因此可以被安全地摇树优化。注意仓库当前实际以type: commonjsdist/形式发布双格式产出由各包 tsconfig 配置驱动从源码结构看thin 成员被设计为可在 engine沙箱内与 web 打包场景中安全复用这正是bundleable的含义。四、导入边界关键约束pieces 与 engine 的依赖红线规则的核心是按包粒度per-package强制实施的导入边界而非按文件夹名pieces 和 engine 可以 importactivepieces/core-utils、activepieces/core-piece-types、activepieces/core-formula、activepieces/core-execution但永远不能importactivepieces/shared即packages/core/shared。这一设计的意义在于**pieces组件**运行在 engine 的隔离沙箱中只能接触到框架无关的薄库如果 pieces 直接依赖activepieces/shared就会把整个平台层的领域模型、socket.io-client、dayjs等重依赖拉进沙箱打包产物显著增大 bundle 体积并可能造成沙箱内外的类型/实例不一致engine是执行引擎本体它同样只依赖薄库来保持自身轻量、可独立部署参见 packages/server/engine/package.json其中仅声明了activepieces/core-utils与activepieces/core-formula两个 core 依赖。4.1 为什么 pieces 能拿到 shared 里的符号pieces-framework 的再导出既然 pieces 不能直接 importactivepieces/shared那 pieces 开发中常见的FlowRunId、ProjectId、SeekPage等类型从哪来答案在activepieces/pieces-framework。它是 pieces 与 core 库之间的唯一合法桥梁将 thin 成员中的符号**再导出re-export**给所有 piece以 packages/pieces/framework/src/index.ts 为例// 从 activepieces/core-utils 再导出 export type { SeekPage } from activepieces/core-utils; // 从 activepieces/core-piece-types 再导出大量 piece 契约 export { ... } from activepieces/core-piece-types;在 framework 的 package.json 中同样可以看到它只声明了activepieces/core-utils与activepieces/core-piece-types两个 core 薄库依赖workspace:*。各 piece 包只需import自activepieces/pieces-framework由 framework 决定哪些 thin 符号可以被暴露——这既满足了 pieces 的开发体验又不破坏导入边界。五、依赖图与分层合理性综合以上信息可以得到完整的 core 依赖图activepieces/core-utils最薄零 core 依赖 │ ├──→ activepieces/core-piece-types │ │ │ └──→ activepieces/core-execution │ └──→ activepieces/shared厚依赖全部四个 thin 成员 │ ├──→ pieces-framework再导出 thin 符号给 pieces └──→ server-*应用层可自由依赖 shared从源码结构看这一分层带来三点收益可测试性thin 库职责单一如 core-piece-types 自带ai-providers.test.ts测试vitest 可直接单测可打包性engine 与 pieces 的沙箱产物只包含薄库代码sideEffects: false保证 tree-shaking 生效无环保证依赖方向永远是从厚到薄thick 依赖 thin杜绝了跨层反向引用导致的循环依赖与初始化死锁。六、参与开发时的自查清单在新增或修改packages/core/下的代码时请对照以下规则自查检查项规则依据命名packages/core/name→activepieces/core-name各 package.json 的name字段例外packages/core/shared保持activepieces/sharedshared/package.json分层目录内顺序 thin → thickutils → piece-types → formula → execution → shared各包dependencies中的workspace:*引用thin 约束thin 成员不得 importactivepieces/shared、activepieces/server-*、任何 piece 包、任何 web/React 包.claude/rules/core-packages.md 规则原文无环依赖图必须保持无环shared 依赖 thin、thin 之间仅向前依赖各包 package.json 依赖声明导入边界pieces 与 engine 可依赖四个 thin 成员严禁依赖 sharedpieces 的符号经activepieces/pieces-framework再导出framework/src/index.ts构建thin 成员双格式CJS ESM、sideEffects: falsecore-utils/package.json 与 tsconfig.lib.json这套规范直接服务于 Activepieces 的运行时架构engine 在隔离沙箱中执行 piece沙箱产物必须最小化因此所有被 piece 与 engine 共享的符号都收敛在薄库中由 framework 统一暴露而平台级领域模型则安心沉淀在厚库shared中供 server 应用层使用。理解并遵守这一边界是避免pieces 拖入整个平台依赖这一经典架构事故的前提。【免费下载链接】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），仅供参考