工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端【免费下载链接】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-hystruct社区 Piece完整讲解其构建方式、源码结构、API Key 认证、Create Job动作与Workflow EventWebhook 触发器的配置方法并深入底层 HTTP 客户端实现。读完你可以在 Activepieces 中独立安装并接入 Hystruct 的 AI 文档结构化 / 数据提取工作流实现创建文档处理任务 → 接收处理完成事件的自动化闭环。1. Piece 是什么Hystruct 集成模块概览Hystruct 是一个 AI 驱动的文档结构化与数据提取平台而 Activepieces 通过社区 Piece 将其能力封装为可视化编排模块。该 Piece 的入口定义位于 packages/pieces/community/hystruct/src/index.ts从源码可以确认以下元信息displayNameHystructdescriptionAI-powered document structuring and data extraction认证方式API KeySecretText定义于 auth.ts动作Actionscreate_job——创建并排队一个新的文档处理任务触发器Triggersworkflow_event——当 Hystruct 工作流事件发生如任务完成、数据更新时触发分类PieceCategory.ARTIFICIAL_INTELLIGENCEAI 类别最低支持版本minimumSupportedRelease: 0.36.1即 Activepieces 平台需不低于该版本才能运行此 Piece作者onyedikachi-david该 Piece 以 npm 包activepieces/piece-hystruct当前版本0.1.7发布属于commonjs模块构建产物入口为./dist/src/index.js类型声明为./dist/src/index.d.ts详见 package.json。2. 源码结构总览packages/pieces/community/hystruct/ ├── src/ │ ├── index.ts # Piece 入口注册认证、动作、触发器 │ ├── i18n/ # 多语言翻译de/es/fr/ja/nl/pt/zh 等 │ └── lib/ │ ├── auth.ts # API Key 认证定义 │ ├── common/ │ │ ├── index.ts # 公共导出 │ │ └── client.ts # Hystruct API 底层调用封装 │ ├── actions/ │ │ └── create-job.ts # Create Job 动作 │ └── triggers/ │ └── workflow-event.ts # Workflow Event Webhook 触发器 ├── README.md # 构建说明 ├── package.json ├── tsconfig.json └── tsconfig.lib.json整体上它遵循 Activepieces 社区 Piece 的标准目录规范index.ts负责注册lib/auth.ts定义认证lib/actions与lib/triggers分别存放动作与触发器lib/common存放可复用的 API 调用逻辑。3. 构建 Piece关联文档 README.md 给出了构建命令turbo run build --filteractivepieces/piece-hystruct该命令通过仓库根目录的 Turbo 任务编排器仅构建activepieces/piece-hystruct这一个包及其依赖的上游 workspace 包。从根目录 turbo.json 可以看到build任务设置了dependsOn: [^build]即会先构建该包的 workspace 依赖如activepieces/pieces-framework、activepieces/pieces-common、activepieces/core-piece-types、activepieces/core-utils再执行本包构建。包内的实际构建脚本定义在 package.jsonscripts: { build: tsc -p tsconfig.lib.json cp package.json dist/, bundle: node ../../../../dist/packages/cli/src/index.js pieces bundle, lint: eslint src/**/*.ts }build先用tsc按tsconfig.lib.json编译 TypeScript 源码到dist/再把package.json复制进dist/保证发布后的 npm 包携带版本与依赖声明bundle调用仓库内的 Activepieces CLIpackages/cli的pieces bundle命令将 Piece 打包为可分发产物适用于本地开发调试场景lint用 ESLint 检查src/**/*.ts的代码规范。4. 认证API Key 的获取与配置该 Piece 使用 API Key 进行认证类型为PieceAuth.SecretText定义于 auth.ts。其required: true表示该 Piece 的每个动作 / 触发器在启用前都必须绑定一个连接Connection。源码内嵌的官方指引文案如下登录 Hystruct 控制台dashboard点击右上角的头像进入Settings点击API Keys复制 API Key 并粘贴到 Activepieces 的连接配置中。从类型层面看SecretTextPropertyboolean对应AppConnectionType.SECRET_TEXT连接类型见 packages/pieces/framework/src/lib/context/index.ts因此在 Activepieces UI 中你需要在 Hystruct Piece 的连接Connections面板中新增一条 Secret Text 类型的连接值即 Hystruct API Key。5. 核心动作Create Job动作create_job定义于 create-job.ts作用是创建一个新的任务并在 Hystruct 工作流队列中排队执行。5.1 输入参数参数类型必填说明workflowIdShortText是要运行的 Hystruct 工作流 ID5.2 底层调用const response await hystructApiCall{ message: string }({ apiKey: context.auth.secret_text, method: HttpMethod.POST, endpoint: /v1/workflows/${workflowId}/queue, });即向POST https://api.hystruct.com/v1/workflows/{workflowId}/queue发起请求响应体为{ message: string }。从aiMetadata标注可以确认两点重要的语义用途按工作流 ID 立即触发一次 Hystruct 文档结构化 / 数据提取工作流运行非幂等idempotent: false每次调用都会独立入队一个任务实例重复调用会重复执行适合按需手动触发而非重复调用取同一结果的场景。该动作的audience: both表示它同时面向普通流程编排与 AI Agent 工具调用场景可被 Agent 作为工具检索aiMetadata 中提供了面向 LLM 的自然语言描述。6. 核心触发器Workflow Event触发器workflow_event定义于 workflow-event.ts采用TriggerStrategy.WEBHOOK策略——即由 Hystruct 平台主动向 Activepieces 推送事件。WEBHOOK策略是 Activepieces 触发器类型的四种内置策略之一完整枚举见 packages/core/piece-types/src/lib/trigger.tsPOLLING/WEBHOOK/APP_WEBHOOK/MANUAL。6.1 触发时机当 Hystruct 向已注册的 Webhook 发送工作流事件时触发典型事件包括任务完成job completed提取数据更新data updated。具体订阅哪些事件类型由 Hystruct 控制台侧配置并可按单个工作流 ID 过滤。6.2 Webhook 配置步骤触发器通过Property.MarkDown在 Activepieces 画布内呈现设置指引完整步骤如下登录 Hystruct进入Integrations点击Webhooks→Create webhook将 Activepieces 生成的 Webhook URL模板变量{{webhookUrl}}粘贴为 Webhook URL选择要订阅的事件可选填写 Workflow ID 以过滤事件只接收该工作流相关的事件点击Save保存。关于{{webhookUrl}}这是 Activepieces 平台在运行时注入的模板变量。在 packages/pieces/framework/src/lib/context/index.ts 中WebhookTriggerHookContext明确包含webhookUrl: string字段该值由平台在每次启用触发器时生成并暴露给触发器渲染的 Markdown 说明。因此你必须先把包含{{webhookUrl}}的触发器添加到流程并发布 / 启用才能拿到真实的 URL 回填到 Hystruct 控制台。6.3 生命周期钩子onEnable/onDisable源码中为空实现注释说明 Webhook 的创建与删除由用户在 Hystruct 控制台手动完成平台不代为调用 Hystruct APIrun(context)return [context.payload.body]——将 Hystruct 推送的原始请求体整体透传给流程的后续步骤test()返回一条模拟事件负载用于画布内测试触发器时预览数据结构。6.4 示例事件负载sampleData提供了标准的示例输出可直接用于下游步骤的字段映射参考{ workflowId: wf_abc123, event: job.completed, data: { jobId: job_xyz789, status: completed, completedAt: 2024-01-15T10:30:00Z } }字段语义workflowId为来源工作流 IDevent为事件类型data内含任务 IDjobId、状态status与完成时间completedAtISO 8601 格式。7. 底层 API 客户端实现所有 Hystruct API 调用统一收敛在 client.ts 的hystructApiCallT函数中其关键实现如下export const HYSTRUCT_BASE_URL https://api.hystruct.com; const response await httpClient.sendRequestT({ method, url: ${HYSTRUCT_BASE_URL}${endpoint}, headers: { x-api-key: apiKey, Content-Type: application/json, }, queryParams: qs, body, });Base URLhttps://api.hystruct.com所有端点均以此拼接鉴权头x-api-key值即连接中保存的 API Keycontext.auth.secret_text内容类型Content-Type: application/json查询参数传入的query对象会逐项过滤null/undefined后字符串化再作为queryParams发送保证空参数不会污染请求HTTP 客户端使用activepieces/pieces-common的httpClient.sendRequest封装与仓库内其他社区 Piece 保持一致的底层网络栈。当前 Piece 的create_job动作即通过该封装发起POST请求若未来扩展更多 Hystruct 端点如查询任务状态、拉取提取结果同样可复用此客户端。8. 分类、版本约束与多语言8.1 分类归属在 index.ts 中该 Piece 被标记为categories: [PieceCategory.ARTIFICIAL_INTELLIGENCE]。PieceCategory枚举定义于 packages/core/piece-types/src/lib/piece.ts其中ARTIFICIAL_INTELLIGENCE用于归类 AI 相关能力因此该 Piece 会在 Activepieces 画布的 AI 分类下展示。8.2 平台版本约束minimumSupportedRelease: 0.36.1表示该 Piece 要求 Activepieces 平台版本不低于0.36.1。在 packages/pieces/framework/src/lib/piece.ts 中可以看到框架在 Piece 创建时会对minimumSupportedRelease做语义化版本校验低于最低支持版本时会回退到当前框架的最低支持版本因此部署时建议核对平台版本与该字段的兼容性。8.3 多语言 i18n该 Piece 内置多语言翻译位于 src/i18n/包含translation.json默认英文以及de、es、fr、ja、nl、pt、zh等语言包。翻译键覆盖 Piece 描述、API Key 获取指引、Create Job动作及其参数、Workflow Event触发器及 Webhook 配置指引说明界面文案会随 Activepieces 平台语言设置自动切换。9. 在 Activepieces 中的接入流程综合上述源码事实将该 Piece 接入 Activepieces 的完整链路为安装 Piece通过 Activepieces 的 Piece 安装流程搜索 / 安装Hystructnpm 包activepieces/piece-hystruct或基于本仓库源码执行turbo run build --filteractivepieces/piece-hystruct构建后本地接入配置连接在 Connections 中新增 Secret Text 连接填入从 Hystruct 控制台Settings → API Keys获取的 API Key编排动作在流程中添加Create Job动作传入目标Workflow ID即可按需排队运行 Hystruct 文档结构化任务监听结果在流程中添加Workflow Event触发器按 6.2 节 在 Hystruct 控制台配置 Webhook 回填{{webhookUrl}}即可在任务完成、数据更新时自动触发下游处理步骤闭环串联典型场景是把Create Job与Workflow Event配合使用——先创建任务再等待完成事件事件负载中的data.jobId/data.status可直接作为后续分支判断与数据消费的依据。小结activepieces/piece-hystruct是一个结构清晰、实现完整的 AI 类别社区 Piece以 API Key 认证为安全边界以create_job动作驱动 Hystruct 文档结构化任务的排队执行以workflow_eventWebhook 触发器承接完成事件底层通过统一的hystructApiCall客户端访问https://api.hystruct.com。开发者既可以按官方 README 一行命令完成构建也可以在画布中零代码完成Hystruct 任务触发 → AI 文档结构化 → 事件回调 → 下游自动化的完整工作流集成。赞分享工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端【免费下载链接】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点击查看免费下载相关推荐5 分钟跑通 open-meteo自托管天气 API 部署完整指南5 分钟跑通 open meteo自托管天气 API 部署完整指南 open meteo 是一个完全开源的天气数据平台open meteo 自托管部署完成后后端API网关数据工程Activepieces Upgrade.chat Piece 集成指南构建、认证配置与 CRM 自动化实战Activepieces Upgrade.chat Piece 集成指南构建、认证配置与 CRM 自动化实战 本篇技术指南围绕 Activepieces 开源工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端Activepieces Fillout Forms 集成 Piece 全解析构建、认证、查询动作与 Webhook 触发器Activepieces Fillout Forms 集成 Piece 全解析构建、认证、查询动作与 Webhook 触发器 本文以开源仓库中 fillout工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考