1. 项目概述为AI助手装上飞书“全能手”如果你正在使用OpenClaw或EnClaws这类AI助手并且日常工作重度依赖飞书那么你很可能遇到过这样的困境想让AI帮你整理一份飞书文档、查询下个会议时间或者往多维表格里加条数据却发现要么权限不对要么操作起来极其繁琐。传统的飞书机器人集成往往需要开发者权限、复杂的应用创建流程以及令人头疼的“机器人身份”与“个人身份”的权限割裂问题。你真正需要的是一个能让AI助手以“你”的身份安全、无缝地操作你个人飞书账号里所有数据的工具包。feishu-skills正是为了解决这个核心痛点而生的。它不是一个单一的插件而是一套完整的、基于OAuth设备流的飞书技能集合。简单来说它让AI助手获得了操作你个人飞书账号的“临时授权”从而可以像你本人一样去读写文档、收发消息、管理日历和任务。最颠覆性的一点在于它的“30秒快速配置”你不再需要去飞书开放平台手动创建应用、配置权限、获取密钥。整个过程AI助手会引导你完成你只需要用手机飞书App扫个码授权一下一切就自动配置好了。这种体验把原本可能需要半小时的开发者流程压缩到了喝口水的功夫。这套技能包覆盖了飞书生态中几乎所有高频操作场景。从基础的文档创建与读取feishu-create-doc,feishu-fetch-doc到复杂的多维表格增删改查feishu-bitable从即时通讯的消息历史查看feishu-im-read到日程管理的日历事件创建feishu-calendar甚至还包括了文件下载、图片OCR识别、用户搜索等实用功能。无论你是想用AI自动生成会议纪要并存入知识库还是想让它帮你整理任务清单、同步项目进度到表格feishu-skills都提供了现成的、开箱即用的能力模块。2. 核心设计思路为什么是OAuth设备流而非机器人令牌在深入实操之前我们必须先理解feishu-skills最核心的设计哲学它坚决摒弃了传统的“机器人所有者令牌”模式转而采用“基于用户的OAuth设备流”。这个选择直接决定了整套工具的安全性、易用性和功能边界。2.1 传统机器人模式的局限与风险在常见的飞书机器人集成方案中开发者会在飞书开放平台创建一个“自建应用”获取一对app_id和app_secret。这组凭证代表的是“应用”本身而非某个具体用户。当AI助手使用这组凭证调用API时它是以“机器人”的身份在操作。这会带来几个严重问题权限隔离与数据可见性机器人只能访问它被显式授权访问的资源。例如如果机器人没有被添加到某个群聊它就看不到该群的消息如果它没有被授权访问某个文档就无法读取其内容。这意味着你需要提前将机器人添加到所有它可能需要接触的群、文档、日历中这在实际协作环境中几乎不可行。操作身份混淆当机器人在群里发言或修改文档时显示的是机器人的名字。这割裂了“个人操作”与“AI代理操作”的连续性其他协作者看到的是机器人在行动而不是“你”在行动有时会引发困惑。安全隐患app_secret是一个高权限密钥一旦泄露攻击者可以以机器人身份进行所有授权范围内的操作。如果这个机器人被授予了广泛权限如访问公司所有文档风险极高。2.2 OAuth设备流的优势与实现feishu-skills采用的OAuth 2.0设备授权流程完美规避了上述问题。其核心流程如下初始化请求当用户首次请求AI执行一个需要飞书权限的操作如“创建文档”时对应的技能脚本如feishu-create-doc会检查本地是否已有该用户的访问令牌。引导授权若没有令牌脚本会向飞书服务器申请一个“设备码”和一个用于验证的“用户码”并返回一个包含授权链接的响应。AI助手会以卡片或链接的形式将这个授权页呈现给用户。用户扫码授权用户用手机上的飞书App扫描二维码或点击链接在飞书内确认授权给feishu-skills应用访问自己的数据如文档、日历等。令牌交换与存储授权成功后feishu-skills的后台服务通过轮询用“设备码”换回代表该用户身份的access_token和refresh_token。这些令牌被安全地存储在用户本地环境的feishu-auth/.tokens/用户open_id/目录下。透明化后续操作获取令牌后AI助手自动重试最初被用户触发的操作。此后该用户的所有相关操作都使用这组个人令牌直到令牌过期。实操心得理解令牌的生命周期这里有一个关键细节换回的access_token有效期通常很短如2小时但配套的refresh_token有效期很长如30天。feishu-skills的token-utils.js模块内置了自动刷新逻辑。当脚本检测到access_token过期时会静默地使用refresh_token去获取新的access_token。这意味着只要用户在30天内至少使用过一次技能就无需重新扫码授权。这种设计在安全短期令牌和用户体验长期免登录之间取得了最佳平衡。2.3 这种设计带来的根本性改变真正的“以用户身份操作”AI助手现在可以访问该用户有权访问的所有飞书资源无需预先配置。你能看到的群聊、文档、日历AI助手都能帮你操作。操作溯源清晰所有通过技能产生的操作如创建的文档、发送的消息在飞书审计日志里都会显示为用户本人的操作责任清晰。安全性提升核心密钥app_secret仅用于初始的OAuth流程交换不用于日常API调用。日常使用的用户令牌权限更低、有效期短且存储在用户本地泄露风险范围大大缩小。多用户支持同一个OpenClaw/EnClaws实例可以为多个用户服务。每个用户的令牌独立存储互不干扰。用户A让AI创建文档只会用到用户A的令牌和权限。这套设计让feishu-skills从一个“功能有限的机器人”进化成了一个“用户能力的延伸器”这是它区别于其他任何飞书集成方案的根本所在。3. 从零开始环境准备与一键式安装部署理解了核心原理我们就可以动手了。feishu-skills的安装过程被设计得极其简单但为了确保万无一失我们仍需按步骤检查环境并执行。3.1 前置环境检查Node.js版本这是最重要的前提。feishu-skills大量使用了现代JavaScript特性并要求使用Node.js内置的fetch函数进行网络请求。因此必须确保你的Node.js版本大于等于18。在终端中运行node -v进行确认。AI助手平台你需要已经安装并可以正常运行OpenClaw或EnClaws中的任意一个。这是技能运行的宿主环境。飞书账户准备一个可正常登录的飞书账号并确保手机已安装飞书App用于后续的扫码授权。3.2 执行一键安装安装过程通过一个统一的install.js脚本完成它负责将所有技能文件夹复制到AI助手能识别的正确位置。# 1. 克隆仓库到本地 git clone https://github.com/hashSTACS-Global/feishu-skills.git # 2. 进入项目目录 cd feishu-skills # 3. 运行安装脚本 node install.js这个install.js脚本内部做了几件关键事情路径探测它会自动检测你的系统上安装的是OpenClaw还是EnClaws并找到对应的技能安装目录例如OpenClaw的~/.openclaw/skills/。批量复制将feishu-skills/目录下所有的技能子文件夹如feishu-create-doc/,feishu-auth/等复制到目标技能目录。权限设置确保复制过去的脚本文件具有可执行权限。完成提示安装成功后脚本会输出明确的成功信息并提示你下一步可以尝试让AI助手帮你配置飞书应用。注意事项关于Windows环境脚本使用了Node.js的fs.cpSync等API这些API在Node.js 16中已稳定支持因此理论上在Windows的PowerShell或CMD中也能正常运行。如果遇到路径问题请确保以管理员身份运行终端并且Node.js版本符合要求。安装后技能文件通常会位于%USERPROFILE%\.openclaw\skills\目录下。3.3 安装后的验证安装完成后无需重启你的AI助手OpenClaw/EnClaws。你可以直接与助手对话尝试触发一个飞书技能。最直观的验证方式就是使用内置的快速配置技能。在你的AI助手对话界面中直接输入帮我设置飞书插件或者Help me set up the Feishu plugin如果安装成功AI助手应该能识别到这个指令并开始执行feishu-quick-setup技能引导你进入下一步的扫码授权流程。如果助手表示不理解该指令请回到上一步检查技能是否被正确复制到了对应的skills目录中。4. 核心技能详解与实战应用指南安装只是第一步feishu-skills的真正威力在于其丰富的技能集。下面我将挑选几个最具代表性、最常用的技能深入剖析其使用场景、参数细节和实战技巧。4.1 文档管理三剑客创建、读取与更新文档操作是最高频的需求。feishu-skills提供了三个核心技能来覆盖完整生命周期。feishu-create-doc智能文档创建这个技能不仅创建文档还能用Markdown语法初始化内容。核心参数title(必填)文档标题。content(可选)文档初始内容支持标准Markdown语法。飞书文档API会将Markdown转换为对应的Block结构。folder_token(可选)目标云空间文件夹的token。如果不提供文档将创建在用户的“我的空间”根目录。实战示例对AI助手说“在飞书‘项目资料’文件夹里创建一个名为‘项目周报-20240527’的文档内容是第一段写‘本周重点完成模块A联调’第二段是个待办列表1. 测试用例评审 2. 性能压测。” AI助手会解析你的指令调用技能并传入类似{“title”: “项目周报-20240527”, “content”: “## 本周重点完成模块A联调\n\n## 待办事项\n1. 测试用例评审\n2. 性能压测”, “folder_token”: “空间文件夹Token”}的参数。注意事项飞书文档对Markdown的支持是子集复杂表格或特殊语法可能无法完美转换创建后建议预览一下。返回的document_id和url务必让AI助手告诉你这是后续读取和更新的唯一依据。feishu-fetch-doc文档内容提取这是知识库构建的基石可以从文档URL或ID中提取纯文本或结构化内容。核心参数doc(必填)飞书文档的URL或doc_id。技能会自动从URL中解析ID。format(可选)输出格式默认为”text”纯文本。也支持”json”返回飞书原始的Block结构适合需要进一步程序化处理的场景。实战技巧批量归档可以结合AI助手的记忆或外部脚本定期抓取指定文件夹下的所有文档提取文本后存入向量数据库构建个人或团队的知识库。内容摘要获取文本后立即让AI助手对其进行总结、提炼要点实现信息的快速消化。feishu-update-doc文档智能更新支持两种更新模式满足不同场景。核心参数doc(必填)目标文档。content(必填)要更新的内容。mode(可选)更新模式。”append”默认在文档末尾新增区块”overwrite”清空文档原有内容后写入新内容。应用场景对比模式适用场景注意事项append日志追加、会议记录补充、连续性的报告更新。内容会添加到文档最末尾不会影响原有结构。overwrite模板化文档刷新如每日站会模板、内容完全替换。危险操作会永久删除旧内容务必谨慎使用。4.2 多维表格 (feishu-bitable)零代码数据管理利器飞书多维表格是轻量级数据库feishu-bitable技能提供了完整的CRUD增删改查能力。核心概念梳理 在调用前必须清晰理解飞书多维表格的层级关系App(应用) -Table(数据表) -View(视图) -Record(记录)。技能的大部分操作都围绕app_token应用标识和table_id表格标识展开。常用操作示例查询记录这是最常用的操作。你需要提供app_token和table_id。技能会自动使用当前用户的OAuth令牌查询该用户有权限访问的视图和记录。// 技能内部逻辑简化示意 const params { app_token: ‘xxx’, table_id: ‘yyy’ }; // 可以添加筛选条件如 filter: ‘CurrentValue.[状态] “进行中”’ const records await fetchBitableRecords(params);实操心得如何获取app_token和table_id打开飞书多维表格在浏览器地址栏中可以看到类似https://example.feishu.cn/base/bascnABCD1234?tabletblXYZ5678的URL。其中bascnABCD1234就是app_tokentblXYZ5678就是table_id。直接把这个URL丢给AI助手它通常能帮你解析出来。新增记录你需要构建一个符合表结构的fields对象。键是字段名值是字段值。对于“人员”字段值应为用户的open_id数组对于“附件”字段值应为飞书文件token数组。// 示例新增一个任务记录 const newRecord { app_token: ‘bascnABCD1234’, table_id: ‘tblXYZ5678’, fields: { ‘任务名称’: ‘编写项目文档’, ‘负责人’: [‘ou_xxxxxx’], // 负责人的open_id ‘截止日期’: 1746000000000, // 时间戳毫秒 ‘状态’: ‘未开始’ } };更新与删除记录更新需要提供记录的record_id和新的fields。删除则只需要record_id。这些ID都可以通过查询操作获得。高级特性字段管理技能也支持获取表格的字段fields定义这在动态构建新增/更新数据时非常有用可以确保传入的数据结构正确。视图管理可以获取视图views列表不同的视图可能带有不同的过滤和排序条件查询时指定view_id可以快速获取特定视角的数据。4.3 日历与任务 (feishu-calendar,feishu-task)个人效率中枢这两个技能将AI助手变成了你的智能日程秘书。feishu-calendar日历事件管理创建事件除了标题、起止时间等基本信息特别要注意attendees参与者参数需要传入参与者的open_id或user_id。AI助手可以结合feishu-search-user技能来解析你提到的同事姓名并转换为对应的ID。查询事件支持按时间范围查询如“今天”、“本周”返回的事件详情中包含会议链接、描述、参与者响应状态等。实用场景自动安排会议“帮我看看明天下午2点到4点有没有空如果有创建一个关于‘项目复盘’的1小时会议邀请张三和李四把会议纪要文档链接放在描述里。”每日日程简报每天早上让AI助手查询你当天的日历事件并整理成一份简洁的日程摘要发给你。feishu-task任务管理中心飞书的任务功能可以与日历、聊天、文档关联feishu-task技能实现了对它的全面操作。核心功能创建任务支持设置截止时间、负责人、优先级、描述等、查询任务列表可按完成状态、负责人等筛选、更新任务状态如标记完成、删除任务。与日历的协同创建的任务如果设置了截止时间通常也会在日历侧边栏显示。通过AI助手你可以实现“把今天邮件里提到的所有待办事项都创建成飞书任务并设置相应的截止时间”这样的自动化流程。4.4 通讯与文件 (feishu-im-read,feishu-docx-download)信息抓取与处理feishu-im-read群聊历史追溯这个技能允许AI助手读取指定群聊的历史消息。你需要提供群的chat_id。如何获取chat_id在飞书群聊的设置页面通常可以在底部或URL中找到。更简单的方法是让AI助手使用feishu-chat技能搜索群名搜索结果中会包含chat_id。使用限制与伦理请务必在合规和尊重隐私的前提下使用此功能。它适用于从项目群、公告群中提取关键信息、自动生成摘要等场景而不是用于监控个人聊天。feishu-docx-download文档附件内容提取这是一个非常强大的“信息消化”技能。当你有一个飞书Wiki页面或云文档里附带了Word、PDF、PPT、Excel等文件时AI助手可以下载它们并提取出文字内容。支持格式技能内部通过飞书API获取文件下载链接并使用纯Node.js库如mammoth处理docxpdf-parse处理PDF进行文本提取无需安装Office或外部依赖。应用场景知识库构建自动下载团队知识库Wiki中的所有附件提取文本后存入向量数据库。信息汇总“帮我下载这个需求文档附件并总结出其中的功能点和验收标准。”数据整理下载Excel附件提取表格数据经AI分析后生成报告。5. 配置深潜与故障排查手册即使有了一键配置理解背后的配置原理对于解决复杂问题至关重要。这里我们深入feishu-skills的配置层和认证层。5.1 凭证解析顺序与多环境适配feishu-skills设计了一套灵活的凭证解析机制以适应OpenClaw和EnClaws的不同运行方式。凭证解析优先级由高到低环境变量(FEISHU_APP_ID,FEISHU_APP_SECRET)这是EnClaws的默认方式。EnClaws在启动技能时会自动将用户在管理界面配置的飞书应用凭证注入到技能进程的环境变量中。因此在EnClaws下你通常无需手动修改任何配置文件。本地配置文件(feishu-auth/config.json)你可以在这个文件里手动写入appId和appSecret。这适用于希望将凭证与OpenClaw主配置分离或进行多应用测试的场景。OpenClaw主配置(~/.openclaw/openclaw.json)这是OpenClaw下的标准配置方式。凭证放在channels.feishu路径下。为什么需要tools.deny配置这是OpenClaw用户最容易出错的地方。OpenClaw本身内置了一个飞书插件也提供了一些以feishu_开头的工具如feishu_doc。如果你不禁止它们AI助手在收到指令时可能会优先调用这些内置工具而不是功能更强大的feishu-skills。内置工具使用的是机器人令牌无法实现OAuth的个人身份操作会导致权限错误或功能不全。正确的OpenClaw配置片段{ “channels”: { “feishu”: { “appId”: “cli_xxxxxxxxxxxxxxxx”, “appSecret”: “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx” } }, “tools”: { “deny”: [ “feishu_doc”, “feishu_create_doc”, “feishu_fetch_doc”, // … 其他所有需要禁用的内置飞书工具名 ], “exec”: { “security”: “full”, “ask”: “off” } } }关键警告tools对象必须与channels同级位于JSON的根层级。绝对不能把它放在channels.feishu里面OpenClaw对channels.feishu.tools的解析规则不同放在那里会导致deny列表被静默忽略从而无法禁用内置工具。5.2 认证流程详解与问题排查尽管有“30秒快速配置”但了解认证流程的细节能帮你快速定位问题。完整的首次认证交互流程用户触发用户对AI说“创建一份文档”。技能检查feishu-create-doc脚本运行首先调用feishu-auth模块检查本地是否有有效用户令牌。返回授权请求无令牌则feishu-auth向飞书服务器发起设备流请求获得device_code和user_code并生成一个验证URL。AI呈现界面脚本返回一个结构化的错误信息{“error”: “auth_required”, “auth_url”: “https://...”, “user_code”: “XXXX”}。AI助手如OpenClaw的界面层会识别这个格式并将其渲染成一个友好的授权卡片展示二维码和用户码。用户扫码授权用户用飞书App扫码在手机上确认授权。后台轮询feishu-auth模块开始以一定间隔轮询飞书服务器询问授权是否完成。令牌获取与存储一旦用户完成授权轮询获得成功响应拿到access_token和refresh_token将其加密后存储到feishu-auth/.tokens/用户open_id/目录下的文件中。自动重试技能脚本在检测到令牌已就绪后会自动重试最初的那个“创建文档”操作。成功执行使用用户令牌调用飞书API创建文档返回结果给用户。常见问题排查表问题现象可能原因解决方案AI助手不响应飞书相关指令1. 技能未正确安装。2. (OpenClaw) 内置工具未禁用AI调用了错误工具。1. 检查~/.openclaw/skills/或EnClaws技能目录下是否存在feishu-*文件夹。2.重点检查OpenClaw配置中tools.deny列表是否正确且位置在根层级。扫码授权后一直提示“授权中”或超时1. 网络问题设备码轮询失败。2. 飞书应用权限配置不全。1. 检查网络连接。技能轮询间隔和超时时间在auth.js中可调但一般无需改动。2. 确保用于扫码的飞书账号对请求的权限如“获取用户基础信息”、“访问文档”点击了“同意”。操作时提示“无权限访问该资源”1. 用户令牌有效但该用户确实无权访问目标资源如文档、群聊。2. 飞书应用未申请对应API权限。1. 这是正常现象OAuth令牌只能访问用户自己能访问的内容。2. 如果是快速配置创建的应用权限是预设好的。如果是自建应用需在飞书开放平台为该应用添加对应权限。之前能用突然提示需要重新授权1.refresh_token已过期超过30天未使用。2. 本地令牌文件损坏或丢失。1. 这是安全策略重新扫码授权即可。2. 检查feishu-auth/.tokens/目录下对应用户的文件是否存在。可尝试删除该文件触发重新授权。EnClaws下环境变量不生效EnClaws技能配置中未正确设置环境变量。在EnClaws的技能管理界面找到feishu-skills相关技能确保其环境变量配置项中已正确注入FEISHU_APP_ID和FEISHU_APP_SECRET。5.3 技能间的协同工作模式feishu-skills不是一个单体应用而是一个松耦合的技能集合。feishu-auth作为认证中心是所有其他技能的基础依赖。这种设计的好处是功能独立你可以只安装你需要的技能。比如你只用文档功能那就不必安装日历、任务相关的技能包。认证共享只要feishu-auth配置好并完成一次用户授权所有其他技能都能共享这个认证状态无需重复授权。易于扩展如果需要增加新的飞书API能力只需参照现有技能的结构创建一个新的技能文件夹并在其实现中调用feishu-auth的令牌管理方法即可。在实际使用中AI助手会根据你的自然语言指令动态地组合调用这些技能。例如你的一句“把今天项目群里的讨论要点总结一下放到我们项目的多维表格里”可能会触发feishu-im-read读群消息、feishu-search-doc找表格、feishu-bitable新增记录等多个技能的串联执行。6. 高级技巧与安全实践在熟练使用基本功能后以下技巧和实践能让你的使用体验更上一层楼同时确保安全无忧。6.1 利用自然语言与AI助手高效交互feishu-skills的强大之处在于与AI助手语言模型的结合。你不需要记忆复杂的命令和参数用自然语言描述你的需求即可。模糊指令的精确解析你可以说“帮我找一下上周三关于产品设计的会议纪要文档”。AI助手会理解“上周三”是一个时间范围并可能组合调用feishu-search-doc按时间、标题关键词搜索和feishu-fetch-doc获取内容来满足你。跨技能工作流指令“查看我今天的日程如果下午有会就提前10分钟在项目群里发个提醒”涉及feishu-calendar查日程、feishu-chat找群、feishu-im-read可能先看下群信息等多个技能。AI助手会规划执行顺序。参数自动补全当你提到“发给张三”时AI助手可以主动调用feishu-search-user技能将“张三”解析为具体的user_id再用于创建日历事件或任务。6.2 令牌管理与安全须知OAuth流程虽然安全但对本地令牌文件的保护同样重要。令牌存储位置feishu-auth/.tokens/目录下每个用户一个子文件夹里面存放加密后的令牌文件。请勿将此目录公开或上传至Git等版本控制系统。项目本身的.gitignore文件通常已忽略此目录。多用户隔离在同一台机器上不同飞书账号扫码授权后会生成不同的令牌文件完全隔离。这适合团队共用一台开发机但使用不同飞书账号的场景。吊销授权如果你怀疑令牌泄露或想取消AI助手的权限最直接的方法是访问飞书开放平台或飞书App的“安全设置”-“第三方应用授权”找到对应的应用名称可能是“feishu-skills”或你快速配置时自定义的名称取消授权。这将立即使所有已颁发的令牌失效。应用权限最小化虽然快速配置的应用已经预设了必要的权限但如果你是自己创建飞书应用应遵循“最小权限原则”只勾选技能实际需要的API权限降低潜在风险。6.3 性能优化与稳定性建议批量操作与速率限制飞书API对调用频率有限制。如果你通过AI助手执行大量连续操作如导出所有文档内容建议在指令中增加“分批处理”、“每操作一次等待片刻”的提示或由技能开发者实现简单的延迟逻辑避免触发限流。错误处理与重试网络波动或API临时故障是常态。feishu-skills中的技能脚本应包含基本的错误处理和重试机制例如对5xx错误进行指数退避重试。作为用户如果遇到偶发性失败简单地重试一次指令往往是有效的。日志查看当技能执行出现非预期错误时可以查看AI助手运行时的日志输出。在OpenClaw中这可能是在终端启动时的输出在EnClaws中可能有独立的日志面板。日志中通常会包含更详细的错误信息有助于定位是网络问题、认证问题还是API参数问题。6.4 自定义与扩展可能性feishu-skills的开源特性意味着你可以对其进行定制。修改现有技能如果你觉得某个技能的返回格式不符合你的习惯或者想增加一些额外的数据处理逻辑可以直接修改对应技能文件夹下的.js文件。例如在feishu-fetch-doc中你可以修改文本提取后的清洗规则。创建新技能参考现有技能的结构你可以很容易地封装一个新的飞书API。只需在feishu-skills目录下新建一个文件夹包含SKILL.md技能描述和主执行文件如my-new-skill.js并在主文件中遵循相同的模式引入feishu-auth进行认证调用飞书API返回结构化结果。然后重新运行node install.js即可。与其他工具集成feishu-skills返回的数据是结构化的JSON这使其可以轻松与其他自动化工具如Zapier, n8n或自定义的Python脚本结合构建更复杂的自动化工作流。我个人在实际使用中最大的体会是这套技能彻底改变了AI助手与办公软件的交互方式。它不再是隔靴搔痒的“外部工具”而是真正成为了一个能够深入你日常工作流、以你的身份去处理信息的智能代理。从被动的问答到主动的代办、整理、提醒和创作生产力的提升是实实在在的。开始可能会花一点时间熟悉各种技能的名称和大致能力但一旦建立起“用自然语言驱动一切”的思维习惯你就会发现管理数字工作的负担大大减轻了。