Activepieces 工程知识库Engineering Brain导读从架构脊柱到交付流水线【免费下载链接】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 的brain/knowledge/engineering/目录是一份面向人机双读者的工程大脑知识库它记录了这个开源 AI 工作流自动化平台monorepo Turbo自托管或云版400 piecesMCP 支持系统如何工作、以及为什么这样设计。本文以这份知识库的枢纽页 brain/knowledge/engineering/index.md 为骨架逐一展开其六大领域与九个核心页面并对照仓库源码给出可验证的实现细节。读完后你将掌握这套知识库的组织规则何时该建页、何时该写决策、gotcha 该放哪并能在packages/server/api、packages/web、packages/tests-e2e、deploy/activepieces-helm等目录中快速定位哪里会踩坑、哪里是权威实现。一、Engineering Brain 是什么一份同时写给人与 Agent 的 wiki按 index.md 的定义Engineering Brain 是 Activepieces 的工程 wiki每一页都点明主题、开门见山、独立成篇方便人快速扫读也方便 Agent 精确检索。它有两个独特的设计约束文件即页面brain/knowledge/下每个文件夹对应 Craftspace 中的一个 Area每个.md文件就是一页团队在 GitHub 与知识库应用中读到的是同一份内容。area/index.md是该 Area 的页面旁边的文件是它的子页。页面是脊索spine而非文集一个 Area 只拥有一页该页是词汇表式的导航脊——每行一个术语定义这个东西是什么。术语膨胀到放不下一行时才晋升为旁边的独立文件。写之前先搜索给已有 Area 再造第二页正是这套结构要防止的失败。二、六大领域Areas总览index.md 把整个工程知识划分为六个领域每个领域一个页面作为速览地图并在页面内点名各自最反直觉的跨切面规则领域覆盖内容一句话要点️ Architecture Spine多租户、版本CE/EE/Cloud、实体注册、SSRF、包布局怎么改才不会破坏东西的起点 Flows Execution流程如何编写、触发、运行与组织面向作者与触发器的运行模型⚙️ Execution Runtime一个 job 在哪里、如何运行Worker-is-Sandbox、Resolver、Slots、Reservations以及执行词汇表 AI MCPAI providers、credits、copilot、把 Activepieces 暴露为 MCP serverAI 能力与计量 Connections Auth登录、RBAC、审计、连接、密钥安全与凭据 Data, Storage ObservabilityTables、Files、KV、变量、审计日志、分析数据存储与可观测性这些页面存放事物现在是什么而**为什么当初做了这个难以逆转的决定**存放在同属该领域的brain/knowledge/decisions/中例如 000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md、000003-engine-posts-run-time-callbacks-directly-to-the-app.md含被否决的替代方案。改动某个子系统前先读对应决策。三、知识组织规则四条约法index.md 给出了四条决定内容归属的规则这是理解整份知识库的关键Gotcha 永不自立成页。它属于所影响功能的Gotchas小节——这样读该功能的人当场遇到它而不是得先知道它存在。以新增 bullet 的方式加入只有当主题是新的才新开页面。Decision 归入其所属领域。它们记录为什么做了某个难逆转的选择以及被否决的替代方案在改动子系统机制之前先读它们。技能skill是侦查规则rule是页面。如果某流程能写成每次恒真的编号步骤清单它就该上 wiki 页——Agent 需要知道它而非执行它。只有当第 3 步做什么取决于第 2 步查到了什么审讯活系统、循着 ClickHouse/BullMQ/Postgres 的证据链走、对每个发现判断可达性、对着活连接抓真实输出时才称得上技能。会跑一条 CLI 命令不是判定标准——一条命令加一页约定仍然是一页。把约定塞进技能会在四个地方CLAUDE.md、.claude/rules/、Architecture Spine、技能本身同时过期而且只在描述恰好命中时才被加载。词汇表内联在 Area 页上尤其 Execution Runtime。一词一义全文统一用词。四、Architecture Spine承重墙与非显性规则architecture-spine.md 是别破坏东西的起点也是仓库中反直觉规则最密集的一页。核心规则速览多租户Platform → Projects → Users 三级。所有DB 查询必须按projectId或platformId过滤多项目访问的连接在projectIds数组列上用ArrayContains([projectId])。版本EditionsCE / EE / Cloud 由AP_EDITION决定EE 通过hooksFactory接缝扩展 CE。CE 代码严禁import src/app/ee/。实体注册是手动的新 TypeORM 实体必须加入 database-connection.ts 的getEntities()迁移导入 postgres-connection.ts 并加入getMigrations()。无自动发现——漏注册会在运行时静默失败。HTTP 约定所有 create/update 用POST删除用DELETE从不PUT/PATCH每个端点都需要securityAccess。副作用隔离触发事件/webhook 的变更放进独立*-side-effects.ts在变更之后显式调用。多服务器并发distributedLock、BullMQ 去重或FOR UPDATE SKIP LOCKED。SSRFserver/{api,worker,utils}中的出站 HTTP 必须用activepieces/server-utils的safeHttp.axios/createAxios对用户/OAuth/第三方 URL 严禁裸fetch/axios.create。自托管任何新环境变量/密钥/piece 认证/DB 扩展必须默认零配置——绝不交付看起来已启用、实则无手动配置就静默损坏的 UI。包布局遵循由薄到厚packages/core/*utils、piece-types、formula、execution是薄而框架无关的双格式包唯一例外是packages/core/shared即activepieces/shared——它是应用级厚包携带 DB/EE schema 与重依赖pieces 与 engine 只能通过activepieces/pieces-framework获取符号严禁导入activepieces/shared。任何对core/shared的改动都需要 bump 其package.json版本patch修复minor新导出。编码约定同样值得全文照做无any、无as类型断言、无deprecatedAPI用activepieces/shared的tryCatch/tryCatchSync做 Go 风格错误命名参数单个解构对象、不可变数据流Zod 消息必须是web/public/locales/en/translation.json的 i18n key用formErrors常量文件顺序为 imports → 导出的 fn/const → helpers → types导出的类型/常量放文件末尾i18next 插值用{var}而非{{var}}。验证命令npm run lint-dev、npm run test-unitvitest、npm run test-apiCE/EE/Cloud。这页的 Gotchas 是仓库长期踩坑的浓缩例如合并main后出现has no exported member多半是staledist/而非坏合并activepieces/core-*的类型经各包构建后的.d.ts解析改了core/execution的类型要连core/shared一起重建distributedLock().runExclusive在竞争下会等满整个timeoutInSecondsdistributed-lock-factory.ts配置retryCount ceil(timeout/200)、retryDelay: 200绝不放上请求路径unique()是 O(n²) 的JSON.stringify比较禁止上热路径kebabCase()不剥离标点做不了 URL slug要用slugify()PGlite 下DeleteResult.affected恒为undefined计数请用.returning(id)迁移时间戳是手挑的整数1815000000000…两个在途 PR 会撞号TypeORM 软删除在 canary/回滚共享库场景不安全须按 expand-contract 推进canary 不代理 websocket——只有/api/*被代理且upgrade websocket时直接返回因此 canary 平台跑的是 prod 前端、websocket 由 prod旧代码终结。五、Server Module Anatomy服务端模块的六文件结构server-module-anatomy.md 定义了packages/server/api/src/app/下一个服务端模块的样子权威范例是tables/模块页面与模块冲突时以模块为准。六个文件按依赖顺序构建共享类型先行Zod schema z.infer类型放packages/core/shared/src/lib/{domain}/从src/index.tsbarrel 导出并 bumppackages/core/shared/package.json。Entity用EntitySchema绝不用装饰器参见tables/table/table.entity.ts...BaseColumnSchemaPart提供id/created/updated外键用ApIdSchemaprojectId列 指向 project 的CASCADE关系每个 join 列带foreignKeyConstraintName数组列{ type: String, array: true, nullable: false }。然后注册进getEntities()。Migration先改实体生成器是拿实体状态与数据库做 diff再从packages/server/api/执行npm run db-migration -- src/app/database/migration/postgres/MigrationName并把生成的MigrationInterface手改成仓库自己的Migration接口——breaking、release根package.json的下个版本与真正可逆的down()三者都是 CI 强制项。最后按时间顺序注册进getMigrations()。Repositoryconst myRepo repoFactory(MyEntity)事务内用myRepo(entityManager)。Service需要打日志时是工厂(log: FastifyBaseLogger) ({ ... })否则是普通对象触发事件/webhook 的变更放进*-side-effects.ts并在变更后显式调用。Controller 模块注册FastifyPluginAsyncZod路由配置声明在 controller之后而非内联POST建/改、DELETE删每路由必须有securityAccess。四种 helper 的适用范围如下Helper适用范围securityAccess.project(principals, permission, { type })project 级、走 RBACsecurityAccess.platformAdminOnly(principals)平台管理员securityAccess.publicPlatform(principals)任意平台成员securityAccess.public()免认证新能力需要往activepieces/shared的Permission枚举加值模块注册于app.ts的 CE 或 EE 区段EE 专属模块放src/app/ee/并用platformMustHaveFeatureEnabled门控EE 扩展 CE 行为用hooksFactory.createT(ceDefault).set(eeImpl)CE 代码严禁 import EE。队列任务加入SystemJobName/WorkerJobType并用systemJobHandlers.registerJobHandler()注册。退役一个SystemJobName是两步删枚举成员之外还要把字符串字面量加进deprecatedJobs数组否则已排队的 job 永远不被清扫、每次扫描都抛No handler for job name。测试放packages/server/api/test/integration/ce/{feature}.test.ts用setupTestEnvironment()createTestContext(app)→ctx.post()/ctx.get()数据库在测试间清空。注意packages/server/api/test/unit/**不在任何 CI 流水线里跑CI 只跑turbo run test-ce test-ee test-cloud check-migrations --filterapi不要把它当安全网。六、Web Feature Anatomy前端功能的组织与错误态哲学web-feature-anatomy.md 定义了packages/web/src/下前端功能feature的样子权威范例是features/tables/。功能目录结构features/{feature}/ api/ # API 客户端 — tables-api.ts, fields-api.ts components/ # React 组件 hooks/ # react-query hooks — table-hooks.ts stores/ # zustand stores有客户端状态时 types/ utils/ index.ts # barrel —— 功能的公共表面跨功能边界的一切都走index.tsReact 组件按名导出纯函数/常量工具先聚合成一个对象tablesApi、tableHooks再整体导出。路由在app/routes/project-routes.tsx注册由ProjectRouterWrapper 守卫组合RoutePermissionGuard、PageTitle、SuspenseWrapper页面组件React.lazy()导入。功能开关用flagsHooks.useFlag()或FlagGuard付费功能前端用LockedFeatureGuard、查询用enabled: platform.plan.flag后端对应platformMustHaveFeatureEnabled()返回 402。翻译只进packages/web/public/locales/en/translation.json其他 locale 是生成的。这页最核心的哲学是主查询失败的就地错误态任何抓取页面主数据的查询失败时用DataFetchErrorStatecomponents/custom/data-fetch-error-state.tsx替代行渲染DataTable接收isError/errorStateEntity/onRetry辅助查询feature flags、piece 元数据、单项抓取则应静默失败。文案刻意不吓人并声明数据安全因为设计对抗的失败模式是用户以为自己的流程丢了。app/query-client.ts的QueryCache.onError目前只做console.error但已把每次失败以querysource 上报 Sentrylib/error-reporting.ts跳过已处理的 401其余 402/403 一律上报。这页的 gotcha 同样极具实操价值packages/web的测试默认跑在node环境vitestenvironment: node碰window的模块需要// vitest-environment jsdomdocblockRadix/cmdk 组件测试须把 root 挂在document.body上npx turbo run lint --filterweb是 web 真正的格式化门禁别用裸 prettier——仓库钉住 prettier 2.8.4会剥掉es5之外所有 trailing commatest/目录不被 web 的 lint glob 覆盖。七、Cloud Deployment Paths代码如何到达 cloud.activepieces.comcloud-deployment-paths.md 描述了.github/workflows/中两条云交付流水线continuous-delivery-canary.yml与continuous-delivery-cloud.yml。两条路径跑同一张 job 图——guard→build-image→deploy-canary→promote-to-production——且都只在 canary 干净部署后才进生产。常规路径Cloud 的workflow_call/定时运行跳过build-imagedeploy-canary拿到空image_tag由 canary 工作流自己构建.canary镜像并跑check-migrations生产最终部署release-candidate标签。覆盖路径cloud-hotfix手动触发后构建一个.beta镜像把 tag 经image_tag交给 canary让它部署的正是生产将拿到的那个产物并传skip_migration_check: true。guardjob 在定时晋升不足一小时前拒绝 hotfix。上游暂存stagingcontinuous-delivery-stg.yml对每次mainpush 构建并用Kamal不是 Kubernetes部署——SSH 到 devops 主机执行kamal deploy --config-fileconfig/{app,worker}.ymlstaging 环境变量写在config/app.yml的env.clear密钥按名列入env.secret并从.kamal/secrets读取。周四的 job 把 staging 正跑的内容重新打为release-candidate。关键 gotchaKamal 在部署时刻才读配置CD 进行中改config/app.yml会静默漏掉改完要kamal deploy --version same tag --config-fileconfig/app.yml --skip-push并逐个容器docker inspectcheck-migrations同时门禁 canary 与云晋升breaking true即回滚不安全见 check-manifest-migrations.tsneeds.build-image.result skipped无法区分定时跳过与guard 拒绝 hotfix所以deploy-canary还必须依赖guard并检查needs.guard.result ! failure绝不要在 Dockerfile 给/var/cache/apt挂 BuildKit 缓存 mountdocker-clean会清掉 deb 且遗留过期 apt 列表最终报Hash Sum mismatch迁移的breaking true与 PR 的⛓️‍ breaking-change标签是两个轴——前者关乎回滚安全、拦部署后者关乎自托管升级影响、由breaking-change-check.yml在 PR 上强制。八、Helm Chart自托管者的 Kubernetes 安装helm-chart.md 对应 deploy/activepieces-helmchart、values.yaml、templates/。它是docker-compose.yml的 Kubernetes 对等物但不是自家 Cloud 的部署方式Cloud 用 Kamal k3s。一个AP_*变量有两条注入路径templates/deployment.yaml按固定顺序拼一个env:列表activepiecesConfig扁平 map渲染为普通value:条目先渲染自带默认只有AP_CONTAINER_TYPE。activepiecesEnvVariablessecret 名→变量名列表的 map渲染为secretKeyRef且optional: true后渲染自带默认把AP_EDITION、AP_EXECUTION_MODE、AP_ENCRYPTION_KEY、AP_JWT_SECRET与 queue/auth 变量路由到 chart不会创建的三个 secret。chart 只创建两个 secret都是data: {} mittwaldsecret-generator注解在集群内填充release-secrets加密密钥与release-jwt-secretPostgres/Redis 来自 Bitnami 子 chart除非禁用。Gotcha同一变量在两个 key 里都设则secret 赢后渲染的覆盖先渲染的activepieces-config-secrets等三个 secret 默认不存在且values.yaml注释指向的deploy/scripts/apply-secrets.sh在仓库里不存在——没有deploy/scripts/目录全靠optional: true兜底AP_EDITIONee必须同时设置AP_EXECUTION_MODE为 SANDBOX 系模式之一否则system-validator.ts在启动时抛错、pod 无法启动错误信息只提 execution mode不提 edition容易被误判为沙箱问题。九、CI PR Review Hygiene塑造评审方式的门禁ci-pr-review-hygiene.md 讲的是PR 如何被评审而非能否构建。三块核心机制Draft-first 流程PR 先以 draft 打开不自动指派人类评审Greptile 的Review draft pull requests开启后首轮 AI 评审在 draft 打开时即落地且随 draft 上的新提交持续重审。按区域的行数门禁pr-size.yml pr-size-check.ts 统计有意义的行数增删行减掉 lockfile、i18n/translation.json、locales/**、快照、dist超预算即失败engineworkerexecution 合计 300、core/shared250、server/api600、packages/web1200packages/pieces与未匹配项只统计不强制piece 自包含、爆炸半径低。可用large-pr-ok标签或revert:标题绕过。diff 来自本地git diff --numstat免疫 GitHub 3000 文件响应上限。评审人指派完全由.github/CODEOWNERS决定无 bot、无 dependabot/renovate 配置。activepieces/core是兜底 owneractivepieces/pieces拥有/packages/pieces/activepieces/platform拥有执行路径/packages/server/engine/、/packages/server/worker/、/packages/core/execution//bun.lock与/brain/以空 owner 列列出从而脱离兜底。强制手段是Codeowners review 仓库规则集require_code_owner_review: true、required_approving_review_count: 1、required_review_thread_resolution: true而非经典分支保护。值得记住的 gotcha证明新测试没有修复就失败要用git checkout merge-base -- file而非git stash仓库有长期残留 stashpop 会冲突且把别人的 untracked 文件写进工作区flow-rerun.test.ts曾是头号 CI flake——活主机调用应改为本地 loopbacknode:httpserver8163ms → 846ms引擎测试中ssrfGuard因未设AP_NETWORK_MODESTRICT而失效且测试超时不要低于项目默认 20s.env.dev是被跟踪的.gitignore的.env*管不到已入索引的路径本地密钥放dev/目录api/worker 通过dist解析activepieces/shared与core-*包改共享代码后先重建再信任类型检查——正确依赖顺序是core/utils→core/piece-types→core/formula→core/execution→core/shared→server/utils→pieces/framework→core/ai-providers从 PR 里撤回文件要从merge-base恢复而非origin/mainlicense/cla依据 commit author email他人分支重开无法自动通过工作流 action 按 major 版本 tag 钉住而非 SHA只有 CodeQL 用 SHA这是刻意的仓库级策略。十、API Endpoints 与 E2E Tests Monitorsapi-endpoints.md 是 REST API 参考的入口正文见docs/endpoints/另有生成的openapi.json。两条基线认证用 Platform Dashboard 生成的 API keyAuthorization: Bearer {API_KEY}分页是游标式limitcursor查询参数响应{ data, next, previous }。端点组覆盖 Projects、Users、User Invitations、Project Members、Connections / Global Connections、Flows / Flow Runs、Sample Data、Pieces、Project Releases、Git Sync、Folders、Templates、Worker Machinesqueue metrics、Embedding。e2e-tests-and-monitors.md 讲的是packages/tests-e2e里一套 Playwright 套件喂给三个互不依赖的消费者CI全新一次性实例、Checkly 监控每 10 分钟打生产 CloudbaseURL: https://cloud.activepieces.com用E2E_EMAIL/E2E_PASSWORD登录、单个 BetterStack 监控。只坏其中一个的改动在别处看起来全是绿的。要点BetterStack 不读仓库而是仓库推给它sync-betterstack-playwright.yml在 push 到main时把scenarios/betterstack/*.flat.spec.jsPATCH 进硬编码监控 4211060单向且只在 merge 时更新.flat.spec.js故意扁平化、复制了登录逻辑修 page object 不等于修监控CI 只在ready-for-e2e标签下跑e2e.yml门禁两个 edition 工作流Turbo strict env mode 只放行globalPassThroughEnv白名单内的变量AP_DEV_PIECES从packages/pieces/**/dist加载而npm run dev不构建它——默认 dev 实例提供0 个 piece需要真实第三方连接的 spec 不能进scenarios/Checkly 与 CI 都会捡到它。十一、Engineering Handbook Playbooks团队如何构建与发布engineering-handbook-playbooks.md 指向随 docs 发布的公开公司手册docs/handbook/Overview、Team、Hiring流程/级别/薪酬、Customer SupportPylon 工作流、语气、处理请求。工程 onboarding 说明团队以一周 sprint在 GitHub 公开推进工程师自主驱动条目PR 指南包括尽早开 draft PR、主动评审他人、每 PR 一名评审、加入 sprint、PR 所有者起草测试场景、把大功能拆成持续合并的小任务。Playbooks 清单覆盖 run EE、构建自托管、BetterStack 搭建、发布、canary 部署、队列指标、基础设施、数据库迁移、结构化日志、安全公告响应、产品公告、前端最佳实践、e2e 测试、测试策略、连接 Claude 到 Chrome、AI 工程指南。页面 gotcha 中特别实用的一条是在 dev 容器外本地跑 EE 的四堵 macOS 墙PGlite 硬拒AP_EDITIONee/cloud要指到真实本地 Postgres新 worktree 里 symlinknode_modules会在运行时引入跨分支源码/类型错位要做真实bun installbun install在 Darwin 25 上会因isolated-vm原生构建失败而整体中止用--ignore-scripts后手动npx prebuild-install -r napi取 sqlite3 预编译绑定仓库要求 Node 22.15zlib.zstdDecompressNode 20 会在file-compressor.ts处崩溃。另一条是DISCORD_ON_CALL_WEBHOOK是唯一贯穿所有 on-call Discord 通知的仓库 secret轮换它一次重指全部。文档媒体图片/视频走 CDN 而非仓库——视频在https://cdn.activepieces.com/videos/docs/文件名.mp4图片在https://cdn.activepieces.com/assets/文件名.png两者路径规则不同切勿互相推断。十二、如何高效使用这份工程知识库综合 index.md 与其子页的自我描述推荐的阅读路径是先读 architecture-spine.md——它是承重结构回答我怎么改才不会破坏东西以及合并后出现幻影类型错误时先查 staledist/。按你要动的子系统进入对应 Area改后端进 server-module-anatomy.md六文件模块权威范本tables/改前端进 web-feature-anatomy.md功能目录与错误态哲学权威范本features/tables/。动一个难以逆转的机制前读brain/knowledge/decisions/里该领域对应的决策避免重复被否决的方案。提交前对照 ci-pr-review-hygiene.md 的行数门禁与 CODEOWNERS 规则涉及数据库改动的把迁移时间戳、breaking/release字段、getEntities()/getMigrations()手动注册逐项核对。涉及发布时cloud-deployment-paths.md 讲清 canary→prod 与 hotfix 覆盖路径helm-chart.md 讲清自托管 K8s 安装的双路径变量注入。这套一页一主题、gotcha 就地归位、决策入档、技能与规则分流的组织法正是整个仓库能在 400 pieces、多服务端包与多版本分支下保持可维护性的元机制——它本身也是值得借鉴的工程 wiki 范本。【免费下载链接】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），仅供参考