@luka-cat-mimi/n8n-nodes-feishu-project

# @luka-cat-mimi/n8n-nodes-feishu-project 在 n8n 中轻松操作飞书项目 —— 无需写代码，拖拽即可实现工作项管理自动化。 ## 为什么选择这个节点？ | 痛点 | 解决方案 | |------|----------| | 飞书项目 API 调用复杂 | **动态表单**：空间、工作项类型自动加载，下拉选择即可 | | 分页数据获取麻烦 | **一键获取全部**：自动处理分页，返回完整数据 | | API 限流导致失败 | **批次处理**：自动控制请求频率，避免触发限流 | | 请求卡死无响应 | **超时保护**：设置超时时间，请求异常及时中断 | ## 安装 ``` npm install @luka-cat-mimi/n8n-nodes-feishu-project ``` 或在 n8n 社区节点中搜索安装，参考：[社区节点安装指南](https://docs.n8n.io/integrations/community-nodes/installation/) ## 节点概览本插件包含两个节点： | 节点 | 类型 | 说明 | |------|------|------| | **飞书项目** | 操作节点 | 调用飞书项目 API，支持工作项、空间、用户、工作流等 68 个操作 | | **监听事件** | 触发器（Webhook） | 接收飞书项目回调事件，按条件触发工作流 | ## 触发器：监听事件通过 Webhook 接收飞书项目的回调事件来触发工作流，固定使用 **POST** 方法。 ### 支持的事件 | 类型 | 事件（编码） | |------|------| | 工作项（100） | 创建（1001）/ 删除（1002）/ 恢复（1004）/ 终止（1005）/ 模版升级（1006）/ 修改字段（1009） | | 节点（200） | 完成（2001）/ 删除（2002）/ 恢复（2003）/ 回滚（2004）/ 修改估分与排期（2005）/ 修改负责人（2006）/ 修改实际工时（2007）/ 多人确认流转（2009） | | 状态（300） | 状态变更（3001） | | 子任务（400） | 新建（4001）/ 删除（4002）/ 完成（4003）/ 取消完成（4004）/ 修改负责人（4005）/ 修改估分（4006）/ 修改排期（4007）/ 修改实际工时（4008）/ 修改字段（4009） | | 空间（500） | 添加成员（5001）/ 删除成员（5002）/ 完成工作移交（5003）/ 拒绝工作移交（5004） | | 插件（600） | 安装（6001）/ 卸载（6002）/ 更新（6003）/ 购买（6004） | 「监听事件」支持通配符 `*`（所有事件），默认选中。 ### 配置回调地址将节点生成的 Webhook URL 填入飞书项目对应的回调地址中： 1. 工作项 / 节点 / 状态 / 子任务 / 空间等业务事件（100~500）：**开发者后台 → 插件功能 → 插件构成添加构成 → 监听事件** 2. 插件安装 / 卸载 / 更新 / 购买等插件事件（600）：**开发者后台 → 插件发布 → 插件事件订阅** ### 验证签名（可选）开启「验证签名」后填入回调 Token，节点会按 `sha256(plugin_id + request_time + token)` 计算签名并与请求体 `signature` 比对，校验失败返回 401。 ### 过滤选项（Options）支持对回调进行多级过滤，判断顺序为：**签名 → 来源类型 → 监听事件 → 飞书项目空间 → 工作项类型**，任一不匹配则忽略（返回 200 但不触发工作流）。 | 选项 | 说明 | |------|------| | **允许来源类型** | 多选：普通用户操作（normal）、OpenAPI（openapi）、系统行为（system）、自动化（automation）。按 `source` 匹配 | | **允许飞书项目空间** | 动态多选，默认通配符。按 `data.project_key` 匹配 | | **允许的工作项类型** | 字符串，支持逗号分隔、JSON 数组或表达式数组（如 `["issue","story"]`、`issue,story`、`{{ ["issue","story"] }}`），默认通配符 `*`。按 `data.work_item_type_key` 匹配；事件不含该字段时视为通过 | ## 支持的功能（68 个操作） <details> <summary>工作项管理（16 个）- 创建、更新、删除、批量操作...</summary> - 创建工作项 / 查询工作项详情 / 更新工作项 / 删除工作项 - 批量更新工作项 / 终止工作项 / 获取工作项元数据 / 获取工作项操作记录 - 获取工作项任务结果 / 批量查询评审信息 / 查询评审结论 / 更新评审 - 创建工时记录 / 获取工时记录列表 / 更新工时记录 / 删除工时记录 </details> <details> <summary>工作项搜索（4 个）- 单空间搜索、复杂条件、全局搜索...</summary> - 单空间工作项搜索 / 复杂条件搜索 / 全局搜索 / 关联工作项搜索 </details> <details> <summary>工作项配置（9 个）- 字段管理、关联配置...</summary> - 获取/更新工作项基础信息 - 创建/获取/更新工作项字段 - 创建/获取/更新/删除工作项关联配置 </details> <details> <summary>空间管理（6 个）- 空间列表、详情、成员...</summary> - 获取空间列表 / 获取空间列表详情 / 获取空间详情 - 获取空间业务线 / 获取空间工作项类型列表 - 获取空间团队成员（支持分页、Return All、自动获取用户详情） </details> <details> <summary>空间关联（4 个）- 工作项关联绑定...</summary> - 获取关联规则列表 / 绑定工作项关联 / 解绑工作项关联 / 获取关联工作项列表 </details> <details> <summary>流程与节点（5 个）- 流程节点操作、状态变更...</summary> - 查询流程节点 / 更新流程节点 / 操作流程节点 / 变更工作项状态 / 获取WBS视图 </details> <details> <summary>子任务（5 个）- 子任务 CRUD...</summary> - 创建子任务 / 获取子任务详情 / 更新子任务 / 操作子任务 / 删除子任务 </details> <details> <summary>视图管理（8 个）- 视图创建、更新...</summary> - 获取视图列表 / 创建条件视图 / 更新条件视图 / 创建固定视图 - 更新固定视图 / 删除视图 / 获取全景视图 / 获取视图工作项列表 </details> <details> <summary>评论管理（4 个）- 评论 CRUD，支持多种对象与内容类型...</summary> - 添加评论 / 查询评论 / 更新评论 / 删除评论 - 支持评论对象类型：工作项（WORKITEM）、工作项字段（WORKITEMFIELD）、子评论（CHILDCOMMENT） - 支持内容类型：纯文本（TEXT）、富文本（RICHTEXT）、附件（FILE） - 查询评论支持分页方向、返回富文本 Markdown </details> <details> <summary>附件管理（4 个）- 工作项附件上传下载...</summary> - 添加附件 / 下载附件 / 删除附件 - 上传文件或富文本图片（通用上传，主要用于富文本中插入图片） </details> <details> <summary>文件管理（2 个）- 评论附件上传下载...</summary> - 上传文件（小于 20MB，用于评论附件或富文本图片，上传后需绑定到业务） - 下载文件（通过 file_token 下载已绑定业务的文件，支持二进制输出） </details> <details> <summary>用户管理（2 个）- 用户信息、用户搜索...</summary> - 获取用户信息 / 搜索租户内的用户列表 </details> <details> <summary>其他（3 个）- 流程模板、角色、群组、度量...</summary> - 创建流程模板 / 获取流程角色列表 / 机器人加入聊天 / 获取图表详情 </details> ## 快速开始 ### 1. 获取凭证 | 凭证 | 获取方式 | |------|----------| | **插件 ID / 密钥** | 飞书项目管理后台 → 插件管理 → 创建或查看插件 | | **用户 ID** | 飞书项目空间左下角 → 双击个人头像 | | **Host** | 通常为 `project.feishu.cn` | ### 2. 配置凭证在 n8n 中创建 **飞书项目 API** 凭据： | 字段 | 示例 | |------|------| | 飞书项目 Host | `project.feishu.cn` | | 插件 ID | `MII_0000000000000000` | | 插件密钥 | `AB92E56666CT8D60704743BF69C92C16` | | 用户 ID | `7568516887894324252` | | 鉴权模式 | 默认开启强制鉴权（`1`），严格按用户 ID 校验权限；设为 `0` 可切换兼容模式 | ### 3. 评论附件工作流示例在评论中插入附件的典型流程： 1. **文件 → 上传文件**：上传二进制文件，获取 `file_token` 2. **评论 → 添加评论**：内容类型选「附件 (FILE)」，填入上一步的 `file_token` 3. **文件 → 下载文件**：文件绑定到评论后，可用 `file_token` 下载 > 上传的文件在未绑定到评论等业务前无法下载，超过 7 天未绑定会自动删除。 ### 4. 开始使用拖入节点 → 选择资源和操作 → 填写参数 → 执行！ ## 注意事项 - 确保插件具有所需 API 的访问权限 - [错误码查询](https://project.feishu.cn/b/helpcenter/1p8d7djs/4bsmoql6) ## 支持 - 邮箱：luka.cat.mimi@gmail.com - [问题反馈](https://github.com/luka-n8n-nodes/n8n-nodes-feishu-project/issues) ## 许可证 MIT License