Activepieces 新 Piece 脚手架：四个配置文件逐项拆解与实战落地指南

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 3（SCAFFOLD）被使用，也就是"全新 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.json：Piece 的包元数据与依赖策略

模板原文：

{ "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" } }

关键字段解读

依赖版本策略

三个 Activepieces 工作区包使用workspace:*协议，指向仓库内真实存在的包（见 packages/pieces/common、packages/pieces/framework、packages/shared）；tslib固定为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.json）；
• devDependencies中的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"]等全局编译基础。随后覆盖的选项都是严格性开关：

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实际使用的编译配置，各字段作用如下：

真实 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 --filter=@activepieces/piece-<name> npx turbo run lint --filter=@activepieces/piece-<name>

• build与lint必须全部通过。lint 失败（未使用导入、any类型、未使用变量）即使构建成功也会阻塞 CI；
• 常见的 TS 错误集中在三处：src/index.ts漏导入、tsconfig.base.json缺少条目、trigger 缺少sampleData；
• 本地联调：在 packages/server/api/.env 中加AP_DEV_PIECES=<name>，启动服务后打开localhost:4200，即可在编辑器中看到并测试新 Piece。

关于已有 Piece 的改动，SKILL.md 还强调了一条版本纪律：每次改动必须 bumppackage.json的version——删除 action/trigger/prop、新增必填 prop、改变既有行为属于MAJOR；新增 action/trigger、新增可选 prop、新增输出字段、修 bug 属于PATCH。不 bump 版本，线上 Flow 永远不会加载到你的改动。

八、模板之外的工程约束速查

最后补充几条与脚手架配套、贯穿整个 Piece 生命周期的约定：

1. 命名即契约：action/trigger 的name字段一旦发布就永久不可变——Flow 按 name 持久化引用，改名会破坏用户线上流程；
2. 认证对象只 import、不 re-export：action/trigger 通过import { myAppAuth } from '../auth'使用认证对象，但index.ts的导出中永远不出现 auth 对象本身；
3. AI 元数据必填：每个手写 action 必须携带audience、aiMetadata、classification，每个 trigger 必须携带aiMetadata与classification: 'READ'（详见 ai-metadata.md），缺失即视为回归；
4. 输出要"表就绪"：嵌套对象要展平（{ 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管严格编译与产物布局。把它们与真实 Piece（airtable、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