ActivePieces Chartly 集成件详解将 Chart.js 配置渲染为可缓存图表图片的 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 社区集成件activepieces/piece-chartly为主体基于该包的 README、package.json与全部源码完整拆解其认证机制、两个动作Create Chart / Get Chart的参数体系、Chart.js 配置组装逻辑与 REST 调用链并给出该集成件的构建与编译方式。读完后你可以理解一个 ActivePieces 社区 Piece 从元数据声明、属性定义、密钥校验到图片产出与缓存复用的完整工程链路。1. 集成件定位与包结构Chartly 集成件的作用用其自身描述来说就是把任意 Chart.js 配置转换成缓存好的 PNG 或 SVG 图片通过一个简单 REST API 完成Instant chart images. Zero servers.。在 ActivePieces 工作流中它属于DEVELOPER_TOOLS与CONTENT_AND_FILES两个分类供流程或 AI Agent 从数值数据直接生成图表可视化。该包的完整文件布局如下包目录src/index.tscreatePiece元数据入口src/lib/common/auth.tsAPI Key 认证定义与在线校验src/lib/actions/create-chart.ts创建图表动作src/lib/actions/get-chart.ts按 ID 取回已缓存图表动作src/i18n/8 种语言翻译de/es/fr/ja/nl/pt/zh 基础 translation.jsonpackage.json 与tsconfig.lib.json包描述与编译配置。从 src/index.ts 的元数据声明可以看到关键事实export const chartly createPiece({ displayName: Chartly, description: Instant chart images. Zero servers. Transform any Chart.js configuration into cached PNG or SVG images via a simple REST API., auth: chartlyAuth, minimumSupportedRelease: 0.36.1, categories: [PieceCategory.DEVELOPER_TOOLS, PieceCategory.CONTENT_AND_FILES], authors: [onyedikachi-david], actions: [createChartAction, getChartAction], triggers: [], });要点minimumSupportedRelease固定为0.36.1createPiece在 packages/pieces/framework/src/lib/piece.ts 中会对该值做 semver 合法性校验并兜底且该 Piece 只声明了两个 action、没有任何 trigger——它是一个纯动作型集成适合被流程或 Agent 按需调用。2. 认证SecretText 密钥 在线校验auth.ts 使用框架的PieceAuth.SecretText定义了一个必填的API Key属性其 description 直接内嵌了 4 步取钥指引到 chartly.dev 生成免费试用密钥、注册账户管理密钥与更高限额、在控制台随时查看、密钥形如trial_abc123...xyz789。validate回调实现了保存连接时即校验的逻辑调用链为GET https://api.chartly.dev/v1/status请求头携带X-Api-Key: 密钥若response.ok为假返回{ valid: false, error: Invalid API key: status statusText }若响应体中status ! ok报告服务不健康Chartly service is currently unhealthy网络异常统一归一为Connection error: message。从源码结构看这是一个典型的轻校验策略只打 status 探针端点不消耗图表生成的配额但能同时覆盖密钥合法性与服务可用性两类故障且所有失败都以结构化{ valid, error }返回便于 UI 展示。3. Create Chart 动作参数、配置组装与调用create-chart.ts 定义了一个name: create_chart、classification: WRITE、audience: both的动作。其属性props体系如下表属性 key类型必填默认值说明chart_typeStaticDropdown是bar8 种类型bar / line / pie / doughnut / radar / polarArea / scatter / bubblechart_titleShortText否—图表标题映射到 Chart.js 的options.plugins.titlelabelsArray是—数据点标签如[Jan, Feb, Mar]dataset_labelShortText是Data数据系列图例名data_valuesArray是—数值序列如[10, 20, 30]background_colorShortText否rgba(54, 162, 235, 0.8)数据点背景色支持rgba(...)或十六进制widthNumber是600图片宽度像素描述范围 1–2000heightNumber是400图片高度像素描述范围 1–2000formatStaticDropdown是png输出格式png或svgbackground_color_imageShortText否white整张图片的背景色支持white/transparent/#FFFFFFadvanced_configLongText否—完整 Chart.js 配置 JSON填写后覆盖其余简单参数3.1 配置组装简单模式与高级模式的二选一run函数首先解构全部 props然后做一条关键分支高级模式若advanced_config非空直接JSON.parse解析失败抛出Invalid JSON in advanced configuration整个配置对象原样下发简单模式否则在客户端拼装标准 Chart.js 结构chartConfig { type: chart_type, data: { labels: labels, datasets: [{ label: dataset_label, data: data_values, backgroundColor: background_color, }], }, options: { responsive: false, // 固定尺寸渲染适配位图导出 }, };若填了chart_title则补充options.plugins.title { display: true, text: chart_title }。responsive: false是位图导出的关键细节——保证画布按width × height固定渲染而不被容器缩放。3.2 API 调用与返回值最终请求体为{ chart: chartConfig, width, height, format }并附加backgroundColor来自background_color_image随后const response await fetch(https://api.chartly.dev/v1/chart, { method: POST, headers: { Content-Type: application/json, X-Api-Key: context.auth.secret_text, }, body: JSON.stringify(requestBody), });非 2xx 时读取错误文本并抛出Chartly API error: status statusText - body成功时将响应二进制读为arrayBufferBase64 编码后组装成 data URL返回对象为{ success: true, chart_url: data:image/${format};base64,${base64Image}, format, width, height, chart_config: chartConfig, // 回传最终生效的配置便于流程后续步骤引用 }值得注意的是其aiMetadata声明了idempotent: false每次调用都会在 Chartly 侧创建一个新的缓存图表Agent 重复调用会产生多个图表 ID——这是创建类动作的固有语义也是它与下文 Get Chart 动作分工的根据。4. Get Chart 动作按 ID 复用缓存图像get-chart.ts 定义name: get_chart、classification: READ的动作aiMetadata.idempotent: true。它只有两个属性chart_idShortText必填来自 Create Chart 的图表 IDformatStaticDropdown可选默认autopng/svg/auto自动探测。执行逻辑要点对空chart_id显式抛出Chart ID is required并对 URL 中使用的 ID 做了trim()处理GET https://api.chartly.dev/v1/chart/{chart_id}携带X-Api-Key404 单独处理抛出带 ID 的友好错误Chart with ID ... not found. Please verify the chart ID is correct.其余非 2xx 沿用统一错误格式从响应头content-type自动判定实际格式含svg判为 SVG含png判为 PNG缺省png把响应二进制转成 data URL。返回{ success, chart_id, chart_url, format, content_type, detected_format }其中format在用户选auto时回落到detected_format。从源码结构看这构成一套写一次、读多次的图像缓存复用模式Create Chart 承担渲染开销Get Chart 只取缓存适合在多条流程分支或多次 Agent 对话轮次中反复引用同一张图而不重复计费/渲染。5. 构建、编译与发布包 README 给出构建入口turbo run build --filteractivepieces/piece-chartly该命令经 turbo 调度到 package.json 中的本地脚本完整工具链如下脚本命令作用buildtsc -p tsconfig.lib.json cp package.json dist/按 tsconfig.lib.json 编译到dist/并把 package.json 拷入产物供main: ./dist/src/index.js解析bundlenode ../../../../dist/packages/cli/src/index.js pieces bundle调用仓库 CLI 生成 Piece bundle运行前提CLI 包已先行构建到dist/linteslint src/**/*.ts仅对src/**做 ESLint 检查运行时依赖全部锁定在 monorepo 工作区内部均为workspace:*activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils另有 devDependencytslib。这意味着该包无法脱离 ActivePieces 仓库独立安装运行——它是典型的 workspace 内 Piece框架 APIcreatePiece、createAction、Property.*、PieceAuth.*都来自 packages/pieces/framework 的activepieces/pieces-framework。6. 国际化与 Agent 元数据除英文基线 translation.json 外src/i18n/目录提供了de/es/fr/ja/nl/pt/zh七种语言的完整翻译覆盖动作显示名、全部属性 label/description 与 8 种图表类型名称——这是 ActivePieces 社区 Piece 的标准 i18n 约定保证非英文用户在流程编辑器和 Agent 工具描述中看到本地化文案。两个动作均携带aiMetadataCreate Chart 说明从简单 props 构造图表或以高级 config 完全接管每次调用都会新建缓存图表故非幂等Get Chart 说明按 ID 取回缓存图像、自动探测 PNG/SVG、只读幂等。这类元数据供 LLM 编排器在工具选择与调用去重时判断动作语义是该集成件能嵌入 AI 工作流的关键一环。7. 小结与延伸阅读Chartly 集成件展示了 ActivePieces 社区 Piece 的一个精炼范例一个SecretText认证 两个读写分工明确的 action约两百行核心代码即覆盖数据到图片的完整链路。相关源码入口元数据packages/pieces/community/chartly/src/index.ts认证与校验packages/pieces/community/chartly/src/lib/common/auth.ts创建动作packages/pieces/community/chartly/src/lib/actions/create-chart.ts取回动作packages/pieces/community/chartly/src/lib/actions/get-chart.ts框架 APIpackages/pieces/framework/src/lib/piece.ts适用前提调用方网络需可达 Chartly APIapi.chartly.dev且持有有效 API Key图表尺寸描述约束为 1–2000 像素。【免费下载链接】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），仅供参考 ActivePieces Chartly 集成件详解：将 Chart.js 配置渲染为可缓存图表图片的 Piece 实现
ActivePieces Chartly 集成件详解将 Chart.js 配置渲染为可缓存图表图片的 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 社区集成件activepieces/piece-chartly为主体基于该包的 README、package.json与全部源码完整拆解其认证机制、两个动作Create Chart / Get Chart的参数体系、Chart.js 配置组装逻辑与 REST 调用链并给出该集成件的构建与编译方式。读完后你可以理解一个 ActivePieces 社区 Piece 从元数据声明、属性定义、密钥校验到图片产出与缓存复用的完整工程链路。1. 集成件定位与包结构Chartly 集成件的作用用其自身描述来说就是把任意 Chart.js 配置转换成缓存好的 PNG 或 SVG 图片通过一个简单 REST API 完成Instant chart images. Zero servers.。在 ActivePieces 工作流中它属于DEVELOPER_TOOLS与CONTENT_AND_FILES两个分类供流程或 AI Agent 从数值数据直接生成图表可视化。该包的完整文件布局如下包目录src/index.tscreatePiece元数据入口src/lib/common/auth.tsAPI Key 认证定义与在线校验src/lib/actions/create-chart.ts创建图表动作src/lib/actions/get-chart.ts按 ID 取回已缓存图表动作src/i18n/8 种语言翻译de/es/fr/ja/nl/pt/zh 基础 translation.jsonpackage.json 与tsconfig.lib.json包描述与编译配置。从 src/index.ts 的元数据声明可以看到关键事实export const chartly createPiece({ displayName: Chartly, description: Instant chart images. Zero servers. Transform any Chart.js configuration into cached PNG or SVG images via a simple REST API., auth: chartlyAuth, minimumSupportedRelease: 0.36.1, categories: [PieceCategory.DEVELOPER_TOOLS, PieceCategory.CONTENT_AND_FILES], authors: [onyedikachi-david], actions: [createChartAction, getChartAction], triggers: [], });要点minimumSupportedRelease固定为0.36.1createPiece在 packages/pieces/framework/src/lib/piece.ts 中会对该值做 semver 合法性校验并兜底且该 Piece 只声明了两个 action、没有任何 trigger——它是一个纯动作型集成适合被流程或 Agent 按需调用。2. 认证SecretText 密钥 在线校验auth.ts 使用框架的PieceAuth.SecretText定义了一个必填的API Key属性其 description 直接内嵌了 4 步取钥指引到 chartly.dev 生成免费试用密钥、注册账户管理密钥与更高限额、在控制台随时查看、密钥形如trial_abc123...xyz789。validate回调实现了保存连接时即校验的逻辑调用链为GET https://api.chartly.dev/v1/status请求头携带X-Api-Key: 密钥若response.ok为假返回{ valid: false, error: Invalid API key: status statusText }若响应体中status ! ok报告服务不健康Chartly service is currently unhealthy网络异常统一归一为Connection error: message。从源码结构看这是一个典型的轻校验策略只打 status 探针端点不消耗图表生成的配额但能同时覆盖密钥合法性与服务可用性两类故障且所有失败都以结构化{ valid, error }返回便于 UI 展示。3. Create Chart 动作参数、配置组装与调用create-chart.ts 定义了一个name: create_chart、classification: WRITE、audience: both的动作。其属性props体系如下表属性 key类型必填默认值说明chart_typeStaticDropdown是bar8 种类型bar / line / pie / doughnut / radar / polarArea / scatter / bubblechart_titleShortText否—图表标题映射到 Chart.js 的options.plugins.titlelabelsArray是—数据点标签如[Jan, Feb, Mar]dataset_labelShortText是Data数据系列图例名data_valuesArray是—数值序列如[10, 20, 30]background_colorShortText否rgba(54, 162, 235, 0.8)数据点背景色支持rgba(...)或十六进制widthNumber是600图片宽度像素描述范围 1–2000heightNumber是400图片高度像素描述范围 1–2000formatStaticDropdown是png输出格式png或svgbackground_color_imageShortText否white整张图片的背景色支持white/transparent/#FFFFFFadvanced_configLongText否—完整 Chart.js 配置 JSON填写后覆盖其余简单参数3.1 配置组装简单模式与高级模式的二选一run函数首先解构全部 props然后做一条关键分支高级模式若advanced_config非空直接JSON.parse解析失败抛出Invalid JSON in advanced configuration整个配置对象原样下发简单模式否则在客户端拼装标准 Chart.js 结构chartConfig { type: chart_type, data: { labels: labels, datasets: [{ label: dataset_label, data: data_values, backgroundColor: background_color, }], }, options: { responsive: false, // 固定尺寸渲染适配位图导出 }, };若填了chart_title则补充options.plugins.title { display: true, text: chart_title }。responsive: false是位图导出的关键细节——保证画布按width × height固定渲染而不被容器缩放。3.2 API 调用与返回值最终请求体为{ chart: chartConfig, width, height, format }并附加backgroundColor来自background_color_image随后const response await fetch(https://api.chartly.dev/v1/chart, { method: POST, headers: { Content-Type: application/json, X-Api-Key: context.auth.secret_text, }, body: JSON.stringify(requestBody), });非 2xx 时读取错误文本并抛出Chartly API error: status statusText - body成功时将响应二进制读为arrayBufferBase64 编码后组装成 data URL返回对象为{ success: true, chart_url: data:image/${format};base64,${base64Image}, format, width, height, chart_config: chartConfig, // 回传最终生效的配置便于流程后续步骤引用 }值得注意的是其aiMetadata声明了idempotent: false每次调用都会在 Chartly 侧创建一个新的缓存图表Agent 重复调用会产生多个图表 ID——这是创建类动作的固有语义也是它与下文 Get Chart 动作分工的根据。4. Get Chart 动作按 ID 复用缓存图像get-chart.ts 定义name: get_chart、classification: READ的动作aiMetadata.idempotent: true。它只有两个属性chart_idShortText必填来自 Create Chart 的图表 IDformatStaticDropdown可选默认autopng/svg/auto自动探测。执行逻辑要点对空chart_id显式抛出Chart ID is required并对 URL 中使用的 ID 做了trim()处理GET https://api.chartly.dev/v1/chart/{chart_id}携带X-Api-Key404 单独处理抛出带 ID 的友好错误Chart with ID ... not found. Please verify the chart ID is correct.其余非 2xx 沿用统一错误格式从响应头content-type自动判定实际格式含svg判为 SVG含png判为 PNG缺省png把响应二进制转成 data URL。返回{ success, chart_id, chart_url, format, content_type, detected_format }其中format在用户选auto时回落到detected_format。从源码结构看这构成一套写一次、读多次的图像缓存复用模式Create Chart 承担渲染开销Get Chart 只取缓存适合在多条流程分支或多次 Agent 对话轮次中反复引用同一张图而不重复计费/渲染。5. 构建、编译与发布包 README 给出构建入口turbo run build --filteractivepieces/piece-chartly该命令经 turbo 调度到 package.json 中的本地脚本完整工具链如下脚本命令作用buildtsc -p tsconfig.lib.json cp package.json dist/按 tsconfig.lib.json 编译到dist/并把 package.json 拷入产物供main: ./dist/src/index.js解析bundlenode ../../../../dist/packages/cli/src/index.js pieces bundle调用仓库 CLI 生成 Piece bundle运行前提CLI 包已先行构建到dist/linteslint src/**/*.ts仅对src/**做 ESLint 检查运行时依赖全部锁定在 monorepo 工作区内部均为workspace:*activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils另有 devDependencytslib。这意味着该包无法脱离 ActivePieces 仓库独立安装运行——它是典型的 workspace 内 Piece框架 APIcreatePiece、createAction、Property.*、PieceAuth.*都来自 packages/pieces/framework 的activepieces/pieces-framework。6. 国际化与 Agent 元数据除英文基线 translation.json 外src/i18n/目录提供了de/es/fr/ja/nl/pt/zh七种语言的完整翻译覆盖动作显示名、全部属性 label/description 与 8 种图表类型名称——这是 ActivePieces 社区 Piece 的标准 i18n 约定保证非英文用户在流程编辑器和 Agent 工具描述中看到本地化文案。两个动作均携带aiMetadataCreate Chart 说明从简单 props 构造图表或以高级 config 完全接管每次调用都会新建缓存图表故非幂等Get Chart 说明按 ID 取回缓存图像、自动探测 PNG/SVG、只读幂等。这类元数据供 LLM 编排器在工具选择与调用去重时判断动作语义是该集成件能嵌入 AI 工作流的关键一环。7. 小结与延伸阅读Chartly 集成件展示了 ActivePieces 社区 Piece 的一个精炼范例一个SecretText认证 两个读写分工明确的 action约两百行核心代码即覆盖数据到图片的完整链路。相关源码入口元数据packages/pieces/community/chartly/src/index.ts认证与校验packages/pieces/community/chartly/src/lib/common/auth.ts创建动作packages/pieces/community/chartly/src/lib/actions/create-chart.ts取回动作packages/pieces/community/chartly/src/lib/actions/get-chart.ts框架 APIpackages/pieces/framework/src/lib/piece.ts适用前提调用方网络需可达 Chartly APIapi.chartly.dev且持有有效 API Key图表尺寸描述约束为 1–2000 像素。【免费下载链接】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），仅供参考