ActivePieces Motion Piece 源码解析构建、API Key 认证与 Motion 任务/项目管理动作实现【免费下载链接】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-motion为载体从 README 给出的构建命令出发逐层剖析该 Piece 的包结构、PieceAuth.SecretText认证校验、动态下拉属性Workspace/Status/Project/Assignee/Task ID的远程选项加载与游标分页机制以及 6 个内置动作 1 个轮询触发器的完整 API 调用链。读完后可掌握在 ActivePieces 中开发一个连接第三方 REST API 的社区件所需的完整骨架。1. Piece 定位与包结构packages/pieces/community/motion/是 ActivePieces 的社区件community piece之一用于对接 Motionapp.usemotion.com的 REST API。从 package.json 可以看到该包的基本信息包名activepieces/piece-motion版本0.1.7入口为./dist/src/index.js依赖activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils均为workspace:*工作区依赖以及用于时间处理的dayjs脚本buildtsc -p tsconfig.lib.json cp package.json dist/即编译 TS 并把package.json拷入产物目录bundle调用 CLI 的 pieces 子命令node ../../../../dist/packages/cli/src/index.js pieces bundle生成可分发的 bundle 包lint对src/**/*.ts执行 eslint。目录结构如下均来自仓库实际文件packages/pieces/community/motion/ ├── src/ │ ├── index.ts # createPiece 入口聚合 auth/actions/triggers │ ├── lib/ │ │ ├── auth.ts # API Key 认证与校验 │ │ ├── common/props.ts # BASE_URL 与可复用动态下拉属性 │ │ ├── actions/ │ │ │ ├── create-task.ts # 创建任务 │ │ │ ├── update-task.ts # 更新任务 │ │ │ ├── create-project.ts # 创建项目 │ │ │ ├── get-task.ts # 按 ID 获取任务 │ │ │ ├── move-task.ts # 跨 Workspace 移动任务 │ │ │ └── find-task.ts # 按名称搜索任务 │ │ └── triggers/ │ │ └── task-created.ts # 任务创建轮询触发器 │ └── i18n/ # de/es/fr/ja/nl/pt/ru/vi/zh 等翻译 ├── package.json └── tsconfig.json / tsconfig.lib.json2. 构建方式README 核心内容README 给出的唯一构建命令是turbo run build --filteractivepieces/piece-motion即通过 Turborepo 在 monorepo 中按包名过滤只构建activepieces/piece-motion这一个依赖树。该命令会触发上面package.json中定义的build脚本先用tsc -p tsconfig.lib.json按 tsconfig.lib.json 编译出dist/产物再复制package.json。需要说明的是--filter只影响 turbo 的包选择最终执行的仍是目标包自身scripts.build中定义的命令。3. Piece 入口createPiece 如何聚合动作与触发器index.ts 是标准 Piece 入口用createPiece声明元数据并把所有动作、触发器注册进去export const motion createPiece({ displayName: Motion, logoUrl: https://cdn.activepieces.com/pieces/motion.png, categories: [PieceCategory.PRODUCTIVITY], auth: motionAuth, authors: [Sanket6652, kishanprmr], actions: [ createTask, updateTask, createProject, getTask, moveTask, findTask, createCustomApiCallAction({ auth: motionAuth, baseUrl: () BASE_URL, authMapping: async (auth) { return { X-API-Key: auth.secret_text }; }, }), ], triggers: [taskCreated], });几个值得注意的实现点categories: [PieceCategory.PRODUCTIVITY]决定该 Piece 在应用市场中的分类auth: motionAuth是整包共用的认证定义见下节所有动作与触发器都引用它最后一个动作由createCustomApiCallAction来自activepieces/pieces-common生成即自定义 API 调用动作它让用户在界面中自由选择 HTTP 方法与路径baseUrl固定为BASE_URLauthMapping负责把认证值映射为X-API-Key请求头——这是 ActivePieces 社区件提供逃生舱式 API 访问的通用手法。4. 认证SecretText /workspaces 探活auth.ts 使用PieceAuth.SecretText声明 API Key 认证export const motionAuth PieceAuth.SecretText({ displayName: API Key, description: You can obtain API key from [API Settings](https://app.usemotion.com/web/settings/api)., required: true, validate: async ({ auth }) { try { await httpClient.sendRequest({ method: HttpMethod.GET, url: ${BASE_URL}/workspaces, headers: { X-API-Key: auth }, }); return { valid: true }; } catch { return { valid: false, error: Invalid API key. }; } }, });从源码结构看其工作原理是用户保存认证时框架会调用validate向 Motion API 发起一次GET {BASE_URL}/workspaces请求并携带X-API-Key头请求成功即判定有效异常则返回Invalid API key.错误。这种以一次轻量只读请求探活的模式是 SecretText 类认证最常用的落地方式。common/props.ts 定义了全包共用的 API 基地址export const BASE_URL https://api.usemotion.com/v1;后续所有动作、触发器、下拉选项的 HTTP 请求都以此为前缀。5. 动态下拉属性体系props.ts 深度解读props.ts 是本件最有复用价值的部分它把 5 个远程选项属性抽象为可复用单元供各动作/触发器共享5.1 workspaceId —— 工厂函数生成的下拉属性workspaceId(displayName)是一个返回Property.Dropdown的工厂函数因为同一属性在 Move Task 动作中会被实例化两次分别标注为 Current Workspace 和 Target Workspace未连接账号时返回disabled: true并提示 Please connect your account.已连接则GET {BASE_URL}/workspaces把响应中workspaces数组的name/id映射为{ label, value }选项。5.2 statusId / projectId / userId —— 依赖 workspaceId 的级联下拉三者结构一致refreshers: [workspaceId]声明了对workspaceId的级联依赖工作区切换后自动刷新选项未选择工作区时同样禁用并提示 Please connect your account and select workspace.。分别请求属性端点响应字段选项映射statusIdStatusGET {BASE_URL}/statuses?workspaceId...[{ name }]label/value 均取nameprojectIdProjectGET {BASE_URL}/projects?workspaceId...projects: [{ id, name }]label 取 namevalue 取 iduserIdAssigneeGET {BASE_URL}/users?workspaceId...users: [{ id, name }]label 取 namevalue 取 id5.3 taskId —— 带游标分页的全量任务下拉taskId属性required展示了处理选项可能很多场景的完整模式do...while循环携带cursor参数反复请求GET {BASE_URL}/tasks?workspaceId...cursor...直到响应meta.nextCursor为空do { if (nextCursor) { qs[cursor] nextCursor; } const response await httpClient.sendRequest({ method: HttpMethod.GET, url: ${BASE_URL}/tasks, headers: { X-API-Key: auth.secret_text }, queryParams: qs, }); const tasks response.body.tasks ?? []; for (const { id, name } of tasks) options.push({ label: name, value: id }); nextCursor response.body.meta.nextCursor; } while (nextCursor);该分页模式在 Find Task 动作与 Task Created 触发器中同样出现是三处共用的数据获取范式。5.4 priority —— 静态下拉Property.StaticDropdown提供 4 个固定选项ASAP、HIGH、MEDIUM、LOWrequired: false与 Motion API 的优先级枚举一一对应。6. 内置动作逐一解析以下 6 个动作均声明了audience: both界面与 AI Agent 均可用及aiMetadata面向 LLM 的工具描述与幂等性标注这使它们可直接被 ActivePieces 的 AI Agent / MCP 场景调用。6.1 Create TaskPOST /taskscreate-task.ts 属性Workspace ID必填、Task Name必填、Description、Due DateProperty.DateTime、Duration分钟数、Status、Priority、Project、Assignee、Labels字符串数组。请求体中有一个关键映射status: propsValue.statusId——下拉的显示值status 名称直接作为请求字段status提交。aiMetadata标注idempotent: false即每次调用都会新建任务。6.2 Update TaskPATCH /tasks/:idupdate-task.ts 以taskId下拉必填定位任务其余字段name、description、dueDate、duration、status、priority、projectId、assigneeId、labels全部可选只更新提供的字段aiMetadata标注idempotent: true。值得留意的一处源码事实请求体中状态字段被写成了staus: statusId见 update-task.ts 中run方法与 Create Task 使用的status键不一致从源码结构看这更像笔误而非 API 约定阅读或移植该动作时应对此保持警惕。6.3 Create ProjectPOST /projectscreate-project.ts 属性Workspace ID、Project Name必填、Description、Due DateISO 8601、Priority、Labels。与创建任务类似aiMetadata标注idempotent: false。6.4 Get TaskGET /tasks/:idget-task.ts 是最简单的动作仅需taskId短文本输入直接GET {BASE_URL}/tasks/{taskId}并返回整个响应体aiMetadata标注idempotent: true只读无副作用。6.5 Move TaskPATCH /tasks/:id/movemove-task.ts 演示了同一动态属性被两次实例化的用法workspaceId(Current Workspace)与newWorkspaceId: workspaceId(Target Workspace)。请求体只包含目标workspaceId把任务移动到指定工作区。6.6 Find TaskGET /tasks 带过滤find-task.ts 按名称搜索任务必填 Workspace ID 与 Task Name可选includeAllStatuses复选框序列化为true/false查询参数、Status、Assignee、Project。与 5.3 相同的游标分页循环会拉完所有匹配页最终返回{ found: result.length 0, result }结构——found布尔值对下游条件分支非常方便。7. Task Created 触发器轮询 时间去重task-created.ts 是唯一的触发器采用TriggerStrategy.POLLING轮询取数polling.items同样以游标分页拉取GET {BASE_URL}/tasks?workspaceId...全量任务然后把每条任务的createdTime用dayjs(task.createdTime).valueOf()转成毫秒时间戳产出{ epochMilliSeconds, data }序列去重策略strategy: DedupeStrategy.TIMEBASED——框架以创建时间作为事件时间基准只推送新于上次水位的任务避免每次轮询重复触发生命周期钩子onEnable/onDisable/test/run全部委托给activepieces/pieces-common的pollingHelperonEnable会在首次启用时初始化轮询状态store 中记录水位这是轮询触发器的标准四件套sampleData触发器内联了一份完整的任务样例含 id、name、dueDate、priority、labels、assignees、createdTime 等字段供界面展示和下游动作的字段提示。触发器只暴露一个属性workspaceId即监听某个工作区的任务创建事件。8. 请求头与认证映射的一致性从源码看本件所有 HTTP 请求认证探活、5 个动态下拉、6 个动作都遵循同一约定认证密钥以X-API-Key请求头传递且写请求POST/PATCH额外携带Content-Type: application/json。createCustomApiCallAction的authMapping也返回X-API-Key: auth.secret_text保证自定义 API 调用与内置动作的认证行为完全一致。认证值在框架侧以auth.secret_text形式提供对应PieceAuth.SecretText的存储语义。9. 国际化与多语言支持src/i18n/目录包含translation.json及 de、es、fr、ja、nl、pt、ru、vi、zh 共 9 个语言的翻译文件覆盖动作/触发器的 displayName 与描述。ActivePieces 的社区件惯例是把界面文案纳入 Crowdin 类多语言流程仓库根目录有 crowdin.yml该目录即为 Motion 件翻译产物的落盘位置。10. 小结一个标准社区件的完整清单以 Motion 件为样本一个可运行的 ActivePieces 社区件至少包含package.jsonworkspace 依赖pieces-framework / pieces-common / core-piece-types / core-utils build/bundle 脚本src/index.tscreatePiece聚合auth、actions、triggers建议以createCustomApiCallAction兜底src/lib/auth.tsPieceAuth.SecretText 一次只读探活请求完成validatesrc/lib/common/props.ts集中BASE_URL与远程选项下拉注意refreshers级联与游标分页src/lib/actions/*.ts每个动作声明name、displayName、audience、aiMetadata含幂等性标注src/lib/triggers/*.ts轮询触发器遵循DedupeStrategy.TIMEBASEDpollingHelper四钩子模式src/i18n/*.json多语言文案构建turbo run build --filteractivepieces/piece-motion。所有结论均可对照仓库中packages/pieces/community/motion/下的源文件直接验证。【免费下载链接】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），仅供参考