企业官网建设流程全解析

Automatisch ClickUp 集成动作实战指南：创建文件夹、列表、任务与按 ID 查找任务

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

本篇文章围绕 Automatisch 官方文档中 ClickUp 应用的动作（Actions）页面展开，逐一拆解"创建文件夹（Create folder）""创建列表（Create list）""创建任务（Create task）""按 ID 查找任务（Find task by id）"四个动作的参数设计、动态数据依赖与底层 ClickUp API 调用，并结合仓库源码给出可验证的实现细节。读完本文，你将能在 Automatisch 的可视化流程编辑器中熟练配置 ClickUp 动作，理解每个字段如何映射到api.clickup.com的真实请求，以及如何利用动态下拉、级联参数和动态字段提高流程的可用性。

一、文档页面与动作清单概览

在 Automatisch 的文档站点中，ClickUp 动作文档 是一份由 YAML 前置元数据驱动的动作清单页面，它通过CustomListing组件渲染出当前 ClickUp 应用可用的全部动作。文档声明的动作共 4 个：

这 4 个动作在源码中有着一一对应的定义文件，集中注册于 动作入口文件，并通过defineAction助手（见 define-action.js）声明。每个动作定义都由三部分构成：name（展示名称）、arguments（参数字段声明）与run($)（实际执行逻辑），这一结构也正是文档清单页能够自动生成的原因——文档中的"名称 + 说明"直接来自动作定义本身。

ClickUp 应用整体注册在 clickup/index.js，其中明确：

• name: 'ClickUp'，key: 'clickup'
• apiBaseUrl: 'https://api.clickup.com/api'（所有动作请求都基于该前缀）
• supportsConnections: true（必须先建立连接才能使用动作）
• 同时注册了triggers、dynamicData、dynamicFields与auth等模块

也就是说，动作只是 ClickUp 集成能力的一半，配合触发器（triggers）与动态数据源（dynamic-data），才能构成完整的自动化流程。

二、动作执行的前提：OAuth2 连接与请求鉴权

在使用任何动作之前，Automatisch 需要先完成 ClickUp 账号的 OAuth2 授权。认证配置定义在 clickup/auth/index.js，需要填写三个字段：

• OAuth Redirect URL：只读字段，值为{WEB_APP_URL}/app/clickup/connections/add，需要原样填入 ClickUp 应用设置中的回调地址；
• Client ID：在 ClickUp App 管理后台创建 OAuth 应用后获得；
• Client Secret：对应的应用密钥。

授权流程由 generate-auth-url.js 实现：它拼接https://app.clickup.com/api?client_id=...&redirect_uri=...&state=...跳转地址，并生成一个随机state用于后续防 CSRF 校验。回调后，verify-credentials.js 会先校验originalState与回调中的state是否一致，再通过POST /v2/oauth/token用code换取access_token与token_type，最后调用/v2/user获取当前用户信息并拼出screenName（用户名 @ 邮箱）用于连接展示。

所有动作请求的鉴权由beforeRequest钩子 add-auth-header.js 统一完成：只要连接数据中存在accessToken，就会在请求头中注入Authorization: {tokenType} {accessToken}。因此，四个动作本身不需要显式处理鉴权，只需关注业务参数。

三、Create folder：在 Space 下创建文件夹

文档对它的说明是"Creates a new folder."。源码实现位于 actions/create-folder/index.js。

参数设计：

其中两个下拉参数都声明了variables: true，意味着可以引用流程中上游步骤的输出作为值。Space 下拉通过dependsOn: ['parameters.workspaceId']实现级联刷新：只有先选中工作区，才会加载该工作区下的空间列表。

实际请求：

const body = { name: folderName }; const { data } = await $.http.post(`/v2/space/${spaceId}/folder`, body);

即调用 ClickUp API 的POST /v2/space/{space_id}/folder，请求体仅包含name。执行成功后通过$.setActionItem({ raw: data })将 ClickUp 返回的完整响应（含新建文件夹的id、name等字段）保存为动作输出，供下游步骤引用。

四、Create list：在 Folder 下创建列表

"Create list" 动作实现在 actions/create-list/index.js，参数比创建文件夹更丰富：

请求体构造逻辑：

const body = { name: listName, content: listInfo }; if (priority) body.priority = priority; if (dueDate) body.due_date = dueDate; const { data } = await $.http.post(`/v2/folder/${folderId}/list`, body);

对应 ClickUp 的POST /v2/folder/{folder_id}/list。值得注意的是，priority和dueDate只有在填写的值非空时才会被放入请求体——这是 Automatisch 动作中常见的"按需组装"模式，避免向 API 发送多余字段。优先级下拉的四个枚举值（Urgent/High/Normal/Low 对应 1/2/3/4）与 ClickUp 官方的优先级映射一致。

五、Create task：在 List 下创建任务（参数最丰富的动作）

"Create task" 是四个动作中参数最多、逻辑最复杂的一个，源码位于 actions/create-task/index.js。

完整参数清单：

两个 dynamic 参数的处理值得单独说明。Assignees与Tags声明为type: 'dynamic'并带fields子结构，运行时会产生一个可增删的多行表单。由于用户可能添加多行，提交时执行逻辑需要把子字段重新组装：

const tags = tagIds.map((tag) => tag.tagId); const assignees = assigneeIds.map((assignee) => Number(assignee.assigneeId));

可见标签直接取子字段tagId字符串；而指派成员会通过Number()转换为数字 ID——这与 ClickUp API 对assignees数组要求整数 ID 的约定保持一致，是源码中一个容易被忽略但很关键的细节。

请求体组装：

const body = { name: taskName }; if (assignees.length) body.assignees = assignees; if (taskStatus) body.status = taskStatus; if (tags.length) body.tags = tags; if (priority) body.priority = priority; if (dueDate) body.due_date = dueDate; if (startDate) body.start_date = startDate; if (markdownContent) { body.markdown_description = taskDescription; } else { body.description = taskDescription; } const { data } = await $.http.post(`/v2/list/${listId}/task`, body);

对应 ClickUp 的POST /v2/list/{list_id}/task。描述字段存在双分支：当markdownContent为 True 时写入markdown_description，否则写入description。另外，status、priority、due_date、start_date等均为可选项，未填写时不会出现在请求体中。

六、Find task by id：按 ID 查询任务详情

文档说明为"Finds a task using id."，实现位于 actions/find-task-by-id/index.js。它是四个动作中唯一的只读动作，适合放在流程中用于校验数据或获取任务详情以驱动后续分支。

参数设计：

其中Use Custom ID字段声明了additionalFields并指向getDynamicFields的listFieldsWhenUsingCustomId动态字段逻辑（见 dynamic-fields/use-custom-id/index.js）：当用户选择"使用自定义 ID"时，界面会动态追加额外字段，引导用户补充自定义 ID 所需的上下文信息，这正是"动态字段"机制在动作中的典型用法。

请求构造：

const params = { custom_task_ids: useCustomId || false, include_subtasks: includeSubtasks, }; const { data } = await $.http.get(`/v2/task/${taskId}`, { params });

对应 ClickUp 的GET /v2/task/{task_id}，两个布尔查询参数分别控制"是否按自定义 ID 查询"与"是否包含子任务"。useCustomId使用|| false兜底，避免未填写时出现undefined。查询结果同样通过$.setActionItem暴露给下游步骤使用。

七、支撑动作的动态数据源：下拉选项从哪来

四个动作中的大量下拉参数都通过source声明为getDynamicData动态数据源，统一注册在 dynamic-data/index.js，共 8 个：

• listWorkspaces：GET /v2/team，返回工作区列表，是几乎所有动作的起点；
• listSpaces/listFolders/listLists：按父级 ID 逐级查询空间、文件夹与列表，支撑"工作区 → 空间 → 文件夹 → 列表"的级联下拉；
• listAssignees/listStatuses/listTags：按列表加载可指派成员、状态与标签；
• listTasks：列出任务，可用于按名称/ID 选择任务。

以 list-workspaces/index.js 为例，其运行逻辑是请求/v2/team，把返回的data.teams映射为{ value: workspace.id, name: workspace.name }选项数组。动态数据源与动作共享同一套鉴权与 HTTP 客户端，因此动作与下拉数据请求的 API 前缀、鉴权头完全一致。

级联关系的实现是动作参数中的dependsOn字段，例如spaceId依赖parameters.workspaceId、folderId依赖parameters.spaceId、listId依赖parameters.folderId。这种声明式依赖保证了用户在可视化编辑器中看到的下拉始终与当前已选父级匹配，不会出现"列表选项来自别的空间"之类的错配。

八、动作输出与触发器配合：构建完整的 ClickUp 自动化

每个动作执行成功后都会调用$.setActionItem({ raw: data })，ClickUp API 的原始 JSON 响应由此成为动作步骤的输出，下游步骤可通过变量引用这些字段（例如拿"创建任务"返回的id去执行"按 ID 查找任务"或写入其他应用）。

若需要"事件驱动"而非"手动触发"，ClickUp 集成还注册了四个触发器（见 triggers/index.js）：newFolders、newLists、newTasks、updatedTask。典型用法是：用"新任务（new task）"触发器监听某列表的新增任务，触发后接"Find task by id"获取完整详情，再用"Create task"把任务复制或迁移到另一个列表，或通过"Create list / Create folder"自动初始化项目结构。动作与触发器结合，即可在不编写代码的前提下覆盖"监听 → 查询 → 写入"的完整自动化链路。

九、小结

• Automatisch 的 ClickUp 集成共提供 4 个动作，其名称与说明与 官方文档清单 完全对应；
• 所有动作以https://api.clickup.com/api为前缀，鉴权由 OAuth2 连接与addAuthHeader钩子统一处理；
• 创建类动作采用"按需组装"请求体：可选字段仅在填写后才发送，Create task还需注意assignees必须为整数 ID、Markdown 描述走markdown_description字段；
• 下拉参数通过getDynamicData动态数据源与dependsOn级联声明驱动，Use Custom ID场景由getDynamicFields动态补充字段；
• 动作输出统一由$.setActionItem暴露，可与 4 个触发器组合成完整的 ClickUp 自动化流程。

如果你想在自己的 Automatisch 实例中验证以上实现，可以按 安装指南 部署后进入 ClickUp 应用，参考 连接文档 完成 OAuth2 授权，再在流程编辑器中依次体验这四个动作。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch