Activepieces 新 Piece 脚手架四个配置文件逐项拆解与实战落地指南【免费下载链接】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时除了src/下的业务代码还需要一套工程配置文件来保证它在 Turborepo 多包仓库中可构建、可 lint、可发布。.agents/skills/piece-builder/new-piece-scaffold.md提供的就是这四份可直接复制使用的模板文件package.json、.eslintrc.json、tsconfig.json、tsconfig.lib.json。本文以该文档为骨架逐文件解释每个字段的作用并结合仓库内 Airtable、Stripe 等真实 Piece 的实现讲清楚从脚手架到接入tsconfig.base.json路径映射、再到构建与本地验证的完整链路。读完本文你将能独立为一个新 Piece 搭建出与仓库现有数百个集成完全一致的工程底座。关联文档new-piece-scaffold.md配套技能总览见 SKILL.md。一、脚手架在整体工作流中的位置Piece Builder 技能将新建 Piece任务划分为 5 个步骤RESEARCH调研→ PLAN规划→ SCAFFOLD搭骨架→ IMPLEMENT实现→ WIRE VERIFY接线与验证。脚手架模板只在Step 3SCAFFOLD被使用也就是全新 Piece模式下才会走到这一步。另外两种模式——为已有 Piece 增加 action/trigger、修复已有 Piece 的 bug——会完全跳过 Step 3直接进入实现与验证阶段。因此这四个文件是从零创建集成的专属基建。Step 3 要求目标目录结构为packages/pieces/community/name/ ├── src/ │ ├── index.ts # createPiece 入口 │ └── lib/ │ ├── auth.ts # 认证定义永远放在这里不要内联进 index.ts │ ├── actions/ # 每个 action 一个文件 │ ├── triggers/ # 每个 trigger 一个文件 │ └── common/ # 共享辅助函数可选 ├── package.json ├── .eslintrc.json ├── tsconfig.json └── tsconfig.lib.json其中后四个配置文件就是本文要逐项拆解的模板。auth.ts只定义认证、不内联进index.ts的约定在现有 Piece 中得到了严格执行例如 airtable/src/lib/auth.ts 与 airtable/src/index.ts 的分工。二、package.jsonPiece 的包元数据与依赖策略模板原文{ name: activepieces/piece-name, version: 0.0.1, main: ./dist/src/index.js, types: ./dist/src/index.d.ts, scripts: { build: tsc -p tsconfig.lib.json cp package.json dist/, lint: eslint src/**/*.ts }, dependencies: { activepieces/pieces-common: workspace:*, activepieces/pieces-framework: workspace:*, activepieces/shared: workspace:*, tslib: 2.6.2 } }关键字段解读字段含义name必须形如activepieces/piece-name与目录名一致这是 Turborepo 过滤和tsconfig.base.json路径映射的匹配键main/types指向./dist/src/index.js与./dist/src/index.d.ts即产物必须落在dist/下构建脚本的第 2 步cp package.json dist/正是为了保证发布产物自包含scripts.buildtsc -p tsconfig.lib.json编译源码随后把package.json复制进dist/供 npm 发布与 Pieces 分发使用scripts.lint对src/**/*.ts执行 ESLintCI 中 lint 失败未使用的导入、any类型、未使用变量即使 build 通过也会阻塞流水线依赖版本策略三个 Activepieces 工作区包使用workspace:*协议指向仓库内真实存在的包见 packages/pieces/common、packages/pieces/framework、packages/sharedtslib固定为2.6.2配合tsconfig.base.json中的importHelpers: true使用。第三方 SDK必须进入dependencies并锁定精确版本。以 Stripe 为例stripe/package.json 中stripe: 18.2.1就是精确定位版本Airtable 则同时携带了airtable: 0.11.6与dayjs: 1.11.9见 airtable/package.json。反观仓库中许多老 Piece 将tslib放进devDependencies而新模板统一放在dependencies这是为了确保运行时依赖完整。真实 Piece 与模板的差异对比真实 Piece 的 package.json 可以发现两处常见扩展新建时按需补齐bundle脚本node ../../../../dist/packages/cli/src/index.js pieces bundle用于将 Piece 打包为可分发的 bundle参考 airtable/package.jsondevDependencies中的tslib老 Piece 的写法。三、.eslintrc.json继承仓库规则并放开本包模板原文{ extends: [../../../../.eslintrc.json], ignorePatterns: [!**/*], overrides: [ { files: [*.ts, *.tsx, *.js, *.jsx], rules: {} }, { files: [*.ts, *.tsx], rules: {} }, { files: [*.js, *.jsx], rules: {} } ] }extends指向仓库根目录的 .eslintrc.json使得每个 Piece 自动继承统一的 ESLint 配置。模板中的三个overrides分片初始为空规则留给实际项目按需收紧。在真实 Piece 中可以看到更具体的实践例如 airtable/.eslintrc.json 在*.ts/*.tsx的 override 里加入了no-restricted-imports禁止从 Piece 引入lodash、activepieces/core-*、activepieces/server*、activepieces/engine、activepieces/shared等包——因为 Piece 需要保持轻量、可独立打包不能反向依赖服务端或核心执行模块。新建 Piece 时如果引用了第三方大依赖建议参照此模式把约束写进 override让 lint 在 CI 阶段自动拦截违规导入。四、tsconfig.json严格模式的总控与工程引用模板原文{ extends: ../../../../tsconfig.base.json, compilerOptions: { module: commonjs, forceConsistentCasingInFileNames: true, strict: true, noImplicitOverride: true, noPropertyAccessFromIndexSignature: true, noImplicitReturns: true, noFallthroughCasesInSwitch: true }, files: [], include: [], references: [{ path: ./tsconfig.lib.json }] }extends指向仓库根目录的 tsconfig.base.json从而获得esModuleInterop、moduleResolution: node、importHelpers: true、target: es2015、lib: [es2022, dom]等全局编译基础。随后覆盖的选项都是严格性开关选项作用module: commonjsPiece 产物以 CommonJS 模块形式输出与运行时加载方式匹配strict打开全部严格类型检查noImplicitOverride强制override关键字防止误覆盖父类方法noPropertyAccessFromIndexSignature禁止通过属性访问索引签名必须用obj[key]避免拼写错误noImplicitReturns要求所有代码路径显式返回noFallthroughCasesInSwitch禁止 switch 分支隐式穿透files: []与include: []表示该文件本身不编译任何源文件仅作为解决方案级配置通过references引用实际的编译工程./tsconfig.lib.json。这种壳配置 子工程引用的结构与 Airtable、Stripe 等真实 Piece 的 tsconfig.json 完全一致真实文件在此基础上还会显式保留forceConsistentCasingInFileNames、strict、noImplicitReturns、noFallthroughCasesInSwitch。五、tsconfig.lib.json真正编译源码的工程模板原文{ extends: ./tsconfig.json, compilerOptions: { rootDir: ., baseUrl: ., paths: {}, outDir: ./dist, declaration: true, types: [node] }, include: [src/**/*.ts], exclude: [jest.config.ts, src/**/*.spec.ts, src/**/*.test.ts] }这是build脚本中tsc -p tsconfig.lib.json实际使用的编译配置各字段作用如下选项作用rootDir: .以 Piece 根目录为编译根保证输出路径与src/结构对应baseUrl: .相对导入的解析基准paths: {}预留的路径别名表通常保持为空跨包依赖统一走tsconfig.base.json的 pathsoutDir: ./dist产物目录与 package.json 的main/types指向一致declaration: true生成.d.ts类型声明供types字段引用types: [node]仅引入 Node.js 类型避免意外拉取浏览器等无关类型include: [src/**/*.ts]只编译src/下的 TypeScript 源码exclude排除 jest 配置与*.spec.ts/*.test.ts测试代码不进产物真实 Piece 的 tsconfig.lib.json 与模板几乎逐字段一致唯一常见差异是新增declarationMap: true生成声明文件对应的 source map便于类型调试。新建 Piece 时可以直接加上这一行。六、接线把新 Piece 注册进tsconfig.base.json仅有四份配置文件还不够。SKILL.md 的 Step 5 明确要求在仓库根目录的 tsconfig.base.json 的paths中按字母序插入一行路径映射否则构建会直接失败activepieces/piece-name: [packages/pieces/community/name/src/index.ts]这一映射是整个 monorepo 的注册表其他包如服务端、Web 前端、引擎正是通过它把activepieces/piece-xxx解析到对应源码入口。从实际内容看tsconfig.base.json 中已经以字母序登记了数百个 Piece 条目例如activepieces/piece-airtable: [packages/pieces/community/airtable/src/index.ts],以及activepieces/piece-stripe、activepieces/piece-slack等。新 Piece 插入时必须保持整体字母序这也是 lint/build 会校验的隐性约定。随后在src/index.ts中通过createPiece定义 Piece参考 airtable/src/index.ts 的结构导入每个 action/trigger 并加入actions: [...]/triggers: [...]同时加入createCustomApiCallAction作为通用的自定义 API 调用入口最后用auth字段挂上auth.ts中定义的认证对象。七、构建、lint 与本地验证四份配置文件就位、tsconfig.base.json注册完成后按以下顺序验证bun install # 仅新 Piece 需要——创建工作区符号链接 npx turbo run build --filteractivepieces/piece-name npx turbo run lint --filteractivepieces/piece-namebuild与lint必须全部通过。lint 失败未使用导入、any类型、未使用变量即使构建成功也会阻塞 CI常见的 TS 错误集中在三处src/index.ts漏导入、tsconfig.base.json缺少条目、trigger 缺少sampleData本地联调在 packages/server/api/.env 中加AP_DEV_PIECESname启动服务后打开localhost:4200即可在编辑器中看到并测试新 Piece。关于已有 Piece 的改动SKILL.md 还强调了一条版本纪律每次改动必须 bumppackage.json的version——删除 action/trigger/prop、新增必填 prop、改变既有行为属于MAJOR新增 action/trigger、新增可选 prop、新增输出字段、修 bug 属于PATCH。不 bump 版本线上 Flow 永远不会加载到你的改动。八、模板之外的工程约束速查最后补充几条与脚手架配套、贯穿整个 Piece 生命周期的约定命名即契约action/trigger 的name字段一旦发布就永久不可变——Flow 按 name 持久化引用改名会破坏用户线上流程认证对象只 import、不 re-exportaction/trigger 通过import { myAppAuth } from ../auth使用认证对象但index.ts的导出中永远不出现 auth 对象本身AI 元数据必填每个手写 action 必须携带audience、aiMetadata、classification每个 trigger 必须携带aiMetadata与classification: READ详见 ai-metadata.md缺失即视为回归输出要表就绪嵌套对象要展平{ user: { name } }→{ user_name }数组记录需键一致可读键名company_name而非cName因为用户常把 Piece 输出接入 Google Sheets 与 Activepieces Tables详见 output-quality.md。结语new-piece-scaffold.md提供的四份模板是整个 Activepieces 数百个社区 Piece 统一工程基座的浓缩package.json管元数据与依赖、.eslintrc.json管质量闸门、双tsconfig管严格编译与产物布局。把它们与真实 Pieceairtable、stripe逐项对照再完成tsconfig.base.json的字母序注册一个新集成就能无缝融入 monorepo 的构建、lint 与本地开发链路。【免费下载链接】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），仅供参考