activepieces re:tune Piece 深度解析构建流程、CustomAuth 鉴权与 AI 聊天机器人动作集成【免费下载链接】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本文以packages/pieces/community/retune的 README 构建说明为主体结合该 Piece 的全部源码讲解如何在 activepieces 中构建 re:tune 集成包、配置其 CustomAuth 鉴权Chat ID API Key 校验机制以及 Ask Chatbot 内置动作和通用 Custom API Call 动作的完整实现细节。读完后可掌握 activepieces 社区 Piece 的标准构建链路tsc → turbo → CLI bundle以及一个含动态下拉选项、鉴权验证和 AI 元数据标注的动作的完整写法。1. 这个包是什么re:tune Piece 的定位与元数据activepieces/piece-retune是 activepieces 社区 Pieces 中的一个 AI 类集成包对应第三方服务 re:tune 的自定义聊天机器人能力。其包名与版本见 package.json{ name: activepieces/piece-retune, version: 0.1.7, main: ./dist/src/index.js, types: ./dist/src/index.d.ts }Piece 的注册入口在 index.ts通过createPiece声明了核心元数据export const retune createPiece({ displayName: re:tune, description: Everything you need to transform your business with AI, from custom chatbots to autonomous agents., auth: retuneAuth, minimumSupportedRelease: 0.30.0, logoUrl: https://cdn.activepieces.com/pieces/retune.png, categories: [PieceCategory.ARTIFICIAL_INTELLIGENCE], authors: [kishanprmr,MoShizzle,abuaboud], actions: [ askChatbot, createCustomApiCallAction({ ... }), ], triggers: [], });从源码结构看该 Piece 的要点是分类PieceCategory.ARTIFICIAL_INTELLIGENCE因此会出现在 activepieces 工作流编辑器的 AI 分类下最低支持版本minimumSupportedRelease: 0.30.0表示该 Piece 需要 activepieces 0.30.0 及以上版本的运行时框架才能加载动作集合只注册了两个 actionaskChatbot与 Custom API Calltriggers为空数组即它不提供事件触发器只能在工作流中作为动作被调用。2. 构建包README 核心命令与完整构建链路关联文档 README.md 的核心内容是构建命令Runturbo run build --filteractivepieces/piece-retuneto build the library.即在 monorepo 根目录执行turbo的 filter 构建turbo run build --filteractivepieces/piece-retune这条命令会命中 package.json 中定义的build脚本结合仓库内的其他脚本完整的构建链路如下脚本命令作用buildtsc -p tsconfig.lib.json cp package.json dist/用库专用 tsconfig 做 TypeScript 编译产物输出到dist/并复制 package.json 供产物包识别依赖bundlenode ../../../../dist/packages/cli/src/index.js pieces bundle调用 activepieces CLI 的pieces bundle子命令把编译产物打成可分发的 Piece bundlelinteslint src/**/*.ts对源码目录执行 ESLint 检查对应的工程文件还包括 tsconfig.json 与 tsconfig.lib.json其中tsconfig.lib.json是构建脚本实际引用的库编译配置。依赖方面该包声明了 4 个 workspace 依赖与 1 个开发依赖dependencies: { activepieces/pieces-common: workspace:*, activepieces/pieces-framework: workspace:*, activepieces/core-piece-types: workspace:*, activepieces/core-utils: workspace:* }, devDependencies: { tslib: 2.6.2 }activepieces/pieces-framework提供createPiece、createAction、PieceAuth、Property等 Piece 开发核心 API见 index.ts 的 importactivepieces/pieces-common提供httpClient、HttpMethod、createCustomApiCallAction等通用能力见 auth.ts 与 ask-chatbot.ts 的 import。3. 鉴权配置CustomAuth、Chat ID 与 API Key 的校验机制re:tune Piece 的鉴权定义在 auth.ts采用PieceAuth.CustomAuth且required: true包含两个属性export const retuneAuth PieceAuth.CustomAuth({ description: markdownDescription, required: true, props: { // There is no way to programmatically get the users chatbots, so we have this chatId: Property.ShortText({ displayName: Chat ID, description: The ID of the chat you want to use., required: true, }), apiKey: PieceAuth.SecretText({ displayName: API Key, description: Your re:tune API key., required: true, }), }, validate: async (auth) { ... }, });两个设计细节值得注意Chat ID 需要手工填写。源码注释明确说明原因There is no way to programmatically get the users chatbots, so we have this——re:tune 没有提供列出工作区全部聊天机器人的接口因此把 Chat ID 作为连接属性由用户从控制台 URL 中复制。API Key 使用PieceAuth.SecretText而非普通文本保证密钥在 activepieces 中以密文形式存储不会明文回显。3.1 凭据获取指引来自源码中的 markdownDescriptiondescription字段是一段展示给用户的多行 Markdown 说明同一段文本同时出现在 index.ts 与 auth.ts 中指导用户获取 Chat ID 与 API Key访问 re:tune 的聊天机器人页面chats 页找到并点击想使用的聊天机器人从浏览器地址栏 URL 中复制 Chat ID。例如 URLhttps://retune.so/chat/acewocwe-123123-123123-123123/中Chat ID 就是acewocwe-123123-123123-123123进入 re:tune 设置页settings滚动到底部找到 Re:tune API Keys复制密钥填入 API Key 输入框。3.2 validate连接建立时的凭据有效性验证validate回调在用户保存连接时执行向 re:tune 发送一个真实请求来验证凭据validate: async (auth) { try { await httpClient.sendRequest{ data: { id: string }[] }({ url: https://retune.so/api/chat/${auth.auth.chatId}/threads, method: HttpMethod.POST, headers: { X-Workspace-API-Key: auth.auth.apiKey, }, body: {}, }); return { valid: true }; } catch (e) { return { valid: false, error: Invalid API key, }; } }从源码结构看该验证逻辑复用了拉取指定 Chat 下会话线程列表这个接口以 POST 方法 空 body 请求/api/chat/{chatId}/threads鉴权头为X-Workspace-API-Key: apiKey。只要请求不抛异常即判定凭据有效任何异常网络错误、401/404 等都会统一折叠为Invalid API key的报错提示。这个接口同时也被第 4 节的 Thread 下拉框复用是整段鉴权与动作链路共享的核心端点。4. 内置动作 Ask Chatbot动态线程下拉与消息发送Ask Chatbot 动作定义在 ask-chatbot.ts用于向已存在的会话线程发送一条消息并取回机器人的回复export const askChatbot createAction({ auth: retuneAuth, name: ask_chatbot, displayName: Ask Chatbot, description: Sends a message to an existing thread with a chatbot., audience: both, aiMetadata: { description: Sends a user message to an existing re:tune chatbot conversation thread and returns the bots generated reply. ..., idempotent: false, }, props: { thread: Property.Dropdown({ ... }), message: Property.ShortText({ displayName: Message, description: The message you want to send., required: true, }), }, async run({ auth, propsValue }) { ... }, });几个实现要点name: ask_chatbot是动作在 flow 定义中的稳定标识snake_case后续修改displayName不影响已发布工作流aiMetadata.idempotent: false显式声明该动作非幂等——每次调用都会向线程追加一轮对话并产生一条新的 AI 响应这对 activepieces 的 AI 编排/重试策略是重要的元数据。4.1 Thread 动态下拉框thread属性使用Property.Dropdown其options回调基于当前连接的 Chat ID 与 API Key 实时拉取线程列表options: async ({ auth }) { if (!auth) { return { disabled: true, options: [], placeholder: Please connect your account first, }; } const options await httpClient.sendRequest({ url: https://retune.so/api/chat/${(auth).props.chatId}/threads, method: HttpMethod.POST, headers: { X-Workspace-API-Key: (auth).props.apiKey }, body: {}, }); return { options: options.body[threads].map((item: any) { return { label: item.name ?? item.id, value: item.id, }; }), }; },从源码结构看这里有两个值得注意的细节未连接账号时返回disabled: true与占位提示保证表单在未鉴权状态下不可操作下拉框实际从响应体body[threads]中映射{ label, value }label 优先取name缺省回退为id。对照 auth.ts 中 validate 的泛型注解{ data: { id: string }[] }可以推断实际响应结构为{ threads: [...] }与下拉框读取的字段一致。4.2 run发送消息并提取回复run方法向 response 端点发起 POST请求体只包含两个字段async run({ auth, propsValue }) { const { thread, message } propsValue; const response await httpClient.sendRequest({ url: https://retune.so/api/chat/${auth.props.chatId}/response, method: HttpMethod.POST, headers: { X-Workspace-API-Key: auth.props.apiKey }, body: { threadId: thread, input: message, }, }); return (response.body as any).response.value; }即调用POST https://retune.so/api/chat/{chatId}/responsebody 为{ threadId, input }返回值直接从响应体的response.value中提取作为该动作步骤的输出供后续步骤引用。5. 通用动作 Custom API Call对 re:tune 任意端点的兜底接入除专用动作外index.ts 还通过createCustomApiCallAction注册了一个通用 HTTP 动作createCustomApiCallAction({ baseUrl: () https://retune.so/api, auth: retuneAuth, authMapping: async (auth) ({ X-Workspace-API-Key: (auth).props.apiKey, }), }),其含义是baseUrl固定为https://retune.so/api用户只需填写相对路径即可访问 re:tune 的任意 API 端点authMapping把连接中的apiKey自动映射为X-Workspace-API-Key请求头用户无需在自定义请求里手工配置鉴权。结合 translation.json 中该动作的表单词条可以确认它暴露了完整的 HTTP 调用参数MethodGET / POST / PATCH / PUT / DELETE / HEAD、Headers、Query Parameters、Body TypeNone / JSON / Form Data / Raw、Body以及高级选项 Response is Binary?、No Error on Failure、Timeout (in seconds)、Follow redirects并提示 Authorization headers are injected automatically from your connection.鉴权头由连接自动注入。6. 国际化与文件清单该 Piece 在 src/i18n 下维护了 9 个语言的译文文件de、es、fr、ja、nl、pt、ru、vi、zh加一份 translation.json 词条源文件覆盖了鉴权表单、Ask Chatbot 与 Custom API Call 的全部展示文本保证界面在德语、日语、中文等 9 种语言下的完整性。完整文件清单相对仓库根目录文件作用README.md构建命令说明本文主体文档package.json包名、版本、build/bundle/lint 脚本与 workspace 依赖src/index.tscreatePiece入口元数据、分类、动作注册src/lib/auth.tsCustomAuth 定义与 validate 校验逻辑src/lib/actions/ask-chatbot.tsAsk Chatbot 动作动态线程下拉 消息发送src/i18n/translation.json界面词条源文件tsconfig.json、tsconfig.lib.json编辑器用与库构建用 TypeScript 配置7. 小结围绕 re:tune Pieceactivepieces 展示了一个社区 AI Piece 的完整工程范式以turbo run build --filteractivepieces/piece-retune一条命令触发 tsc 编译与 CLI bundle 打包以PieceAuth.CustomAuth承载手工 Chat ID 密文 API Key的鉴权模型并通过复用线程列表接口完成连接校验以ask_chatbot动作演示了动态下拉选项、aiMetadata.idempotent标注与响应字段提取的写法再以createCustomApiCallAction提供带自动鉴权头映射的兜底 HTTP 能力。对于需要集成 re:tune 类会话式 AI 服务的场景这套鉴权即验证 动态选项 自定义调用兜底的模式可以直接借鉴。【免费下载链接】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），仅供参考