Description
飞书项目 N8N 集成插件
一个功能完整的 N8N 自定义节点，用于集成飞书项目 (Feishu Project) API，支持工作项管理、空间管理、用户管理、附件处理等全方位功能。
🚀 特性
- ✅ 16个功能模块，覆盖飞书项目的主要API功能
- ✅ 73个操作，支持完整的工作流自动化
- ✅ 安全认证，自动管理插件Token和用户认证
- ✅ 文件上传，支持多种格式的附件管理
- ✅ 统一参数，采用JSON格式的一致性参数设计
- ✅ 错误处理，完善的异常处理和用户提示
- ✅ TypeScript支持，完整的类型定义和智能提示
📦 安装
方式一：NPM 安装 (推荐)
npm install @luka-cat-mimi/n8n-nodes-feishu-project
方式二：手动安装
- 下载项目到本地
- 编译项目
npm install
npm run build
- 将编译后的文件复制到 N8N 的
custom目录
⚙️ 配置
1. 创建凭据
在 N8N 中创建新的 "飞书项目 API" 凭据，填入以下信息：
| 字段 | 说明 | 示例 |
|---|---|---|
| 飞书项目host | 飞书项目的基础host地址 | project.feishu.cn |
| 插件ID | 飞书项目插件的ID | MII_0000000000000000 |
| 插件密钥 | 飞书项目插件的密钥 | AB92E56666CT8D60704743BF69C92C16 |
| 用户ID | 用户的唯一ID，用于X-USER-KEY头部 | 7568516887894324252 |
2. 获取凭据信息
插件ID和插件密钥
- 登录飞书项目管理后台
- 进入插件管理页面
- 查看或创建插件，获取插件ID和密钥
用户ID
- 打开浏览器开发者工具
- 登录飞书项目
- 在网络请求中查看
X-USER-KEY头部信息
📊 功能模块
核心功能
| 模块 | 操作数 | 主要功能 |
|---|---|---|
| 🔐 插件相关 | 1 | 获取plugin_token |
| 👥 用户管理 | 4 | 用户查询、搜索、用户组管理 |
| 🏢 空间管理 | 5 | 空间列表、详情、业务线、团队成员 |
| 📎 附件管理 | 4 | 文件上传、下载、附件添加删除 |
工作项功能
| 模块 | 操作数 | 主要功能 |
|---|---|---|
| 🔍 工作项实例搜索 | 5 | 单空间、跨空间、复杂搜索、全局搜索 |
| 📝 工作项实例读写 | 16 | CRUD操作、批量更新、状态管理、评审管理 |
| ⚙️ 工作项配置 | 9 | 基础信息、字段配置、关联配置 |
| 🔗 空间关联 | 4 | 关联规则、工作项绑定解绑 |
流程管理
| 模块 | 操作数 | 主要功能 |
|---|---|---|
| 🔄 流程与节点 | 5 | 流程详情、节点更新、状态变更 |
| 📋 流程配置 | 5 | 流程模板管理、配置更新 |
| 👤 角色与人员配置 | 1 | 流程角色管理 |
协作功能
| 模块 | 操作数 | 主要功能 |
|---|---|---|
| 📌 子任务 | 6 | 子任务生命周期管理 |
| 👁️ 视图 | 8 | 视图配置、工作项展示 |
| 💬 评论 | 4 | 评论CRUD操作 |
| 👥 群组 | 1 | 机器人加入聊天 |
| 📈 度量 | 1 | 图表详情 |
🛠️ 使用示例
基础用法
- 添加飞书项目节点到工作流
- 选择资源类型（如"用户管理"）
- 选择具体操作（如"搜索租户内的用户列表"）
- 配置参数：
- 路径参数：直接填入（如项目KEY）
- 请求体参数：JSON格式，有默认值
用户查询示例
{
"user_keys": ["7568516887894324252"],
"out_ids": [],
"emails": ["user@example.com"],
"tenant_key": "your_tenant_key"
}
工作项搜索示例
{
"work_item_name": "需求",
"user_keys": ["7568516887894324252"],
"work_item_type_keys": ["story"],
"page_num": 1,
"page_size": 10,
"expand": {
"need_workflow": true,
"need_user_detail": true
}
}
文件上传示例
- 使用 "Read Binary File" 节点读取文件
- 连接到 "飞书项目" 节点
- 选择 "附件管理" > "文件上传"
- 设置
binaryPropertyName为 "data"（默认值） - 填入项目KEY等路径参数
🔧 开发
项目结构
n8n-nodes-feishu-project/
├── credentials/ # 凭据定义
│ └── FeishuProjectApi.credentials.ts
├── nodes/ # 节点定义
│ └── FeishuProject/
│ ├── FeishuProject.node.ts
│ └── resource/ # 资源模块
│ ├── user/ # 用户管理
│ ├── space/ # 空间管理
│ ├── attachment/ # 附件管理
│ └── ... # 其他模块
└── package.json
构建命令
# 开发模式
npm run dev
# 构建
npm run build
# 代码检查
npm run lint
# 格式化代码
npm run format
添加新功能
- 在
nodes/FeishuProject/resource/下创建新模块文件夹 - 创建资源定义文件
ModuleResource.ts - 在模块文件夹下创建操作文件
OperateFile.ts - 使用统一的参数模式：路径参数 + JSON请求体
🤝 贡献
欢迎提交 Issue 和 Pull Request！
贡献指南
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开 Pull Request
📝 许可证
本项目采用 MIT 许可证。详情请参见 LICENSE 文件。
🆘 支持
- 📧 邮箱：luka.cat.mimi@gmail.com
- 🐛 问题反馈：GitHub Issues
- 📖 飞书项目API文档：官方文档
⭐ 致谢
感谢 N8N 提供的强大自动化平台，以及飞书项目团队提供的完善API接口。
如果这个项目对你有帮助，请给它一个 ⭐️！
