大家好我是你们的技术博主。今天想聊一个比较“实在”的话题WorkBuddy。很多同学刷到 WorkBuddy 时第一反应大概率是“这又是个 AI 套壳工具吧”“跟飞书、企业微信连起来有什么用”“官网文档写得稀碎教程全要付费怎么学”我一开始也有这个困惑。直到我把项目源码、文档和 10 节实操课全部梳理了一遍又亲手在飞书和企业微信里把机器人跑通之后才真正理解 WorkBuddy 的价值。这篇文章我就把这套完整的学习路线和实战过程开放出来。从零开始带你把 WorkBuddy 的安装、配置、飞书接入、企业微信接入、任务待办、消息推送全部跑通。内容偏“手把手 源码级”讲解适合真正想动手的人。如果你之前对 WorkBuddy 一直处于“听说过、没跑过”的状态那这篇文章应该能帮你省下大量查资料的时间。文章比较长建议先收藏再阅读。1. WorkBuddy 是什么为什么它能连接飞书和企业微信1.1 WorkBuddy 解决的问题WorkBuddy 本质上是一套面向个人和团队的 AI 工作助理框架。它不只聊天更核心的能力是“接任务”和“办事情”。在很多工作场景中我们是这样使用工具的在飞书群聊里收到一个任务需要抽时间整理成待办企业微信收到客户消息需要在多个系统之间流转再回到企微回复内部多个 AI 工具、知识库、定时任务散落在不同平台缺少统一调度入口。WorkBuddy 做的事情就是把这些场景统一到一个“任务调度中枢”里。它支持通过飞书机器人、企业微信机器人等 IM 渠道收发消息再结合 Skill技能、定时任务、API 调用完成“接收指令 - 处理任务 - 推送结果”的闭环。简单说你不是在使用一个聊天机器人而是在搭建一个“能干活”的 AI 助手底座。1.2 核心概念先扫盲在开始之前先统一一下术语。后面所有配置都会围绕这几个概念展开概念通俗理解在 WorkBuddy 中的定位Agent智能体负责接收用户输入分析意图调度后续动作Skill技能一个可复用的能力单元例如“创建飞书待办”“发送企微消息”Channel渠道消息入口例如飞书、企业微信、WebTask任务一个具体执行单元可能是一次查询、一次 API 调用Tool/API工具与外部系统交互的接口封装如飞书开放平台接口Trigger触发器定时任务、关键词触发、消息事件触发WorkBuddy 的架构大致可以理解为消息进入 ChannelAgent 解析意图匹配对应 SkillSkill 调用具体 Tool/API 完成任务最后把结果原路返回。1.3 为什么开发者和团队需要它如果只是做一个“能聊天的机器人”选择其实很多。WorkBuddy 更值得学习的点在于多渠道统一飞书、企业微信可以接入同一个 Agent 实例实现一处配置、多端使用。任务闭环不只是回复文本还能创建待办、发出审批、触发自动化流程。可编程扩展通过 Skill 机制把重复工作沉淀成可复用能力。开源可控整套代码和文档开源方便二次开发和私有化部署。所以这篇文章的核心思路不是教你“把机器人跑起来”而是教你“把机器人和真实工作流接起来”。2. 环境准备与版本约定2.1 系统环境我在本地和云服务器上都测试过 WorkBuddy 部署。推荐的环境如下操作系统Linux如 Ubuntu 20.04/22.04或 macOSWindows 使用 WSL2 也可以CPU 内存2C4G 起步建议 4C8G因为要跑 Node 服务、可能还会拉起 Python 脚本网络需要能访问飞书开放平台、企业微信开放平台接口如果你的服务器上没有 Docker也可以直接跑源码。下面会给出两种方式。2.2 运行环境版本本文示例以以下环境为准Node.js 18 或 20 LTSpnpm 8 或 npm 9Python 3.10部分 Skill 脚本用到Redis 7.x用于任务队列缓存可选版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.3 需要提前准备的应用账号平台需要准备什么用途飞书飞书开放平台企业自建应用提供机器人能力、获取 app_id/app_secret企业微信企业微信自建应用或群机器人提供消息推送与接收能力GitHub可访问源码仓库的账号拉取代码、查看文档这里强调一下飞书和应用微信都需要“企业/团队”管理员权限才能创建应用。如果没有管理后台可以先用自己的企业认证或测试团队来练习。3. 核心配置与基础知识拆解在实战之前先把几个关键配置原理搞清楚。否则后面报错了你都不知道问题出在哪。3.1 飞书开放平台配置基础飞书接入 WorkBuddy 的核心是“自建应用”。企业管理员登录飞书开放平台创建应用后你会得到App ID应用的唯一标识App Secret应用的密钥用于获取访问令牌tenant_access_token这里面有几个关键权限点机器人能力自建应用需要开通“机器人”能力这样用户才能和你的应用对话。权限范围例如im:message、contact:user.base:readonly等取决于你让 WorkBuddy 做什么。事件订阅WorkBuddy 接收飞书消息依赖事件订阅。飞书会把用户发消息的事件 POST 到你的服务器地址。一个重要概念飞书的“事件订阅地址”需要公网可达。本地调试可以用内网穿透工具安全起见建议在测试阶段就使用临时域名。3.2 企业微信接入方式企业微信接入 WorkBuddy 有两种常见方式自建应用 接收消息服务器适合双向交互企业员工发消息给应用WorkBuddy 处理后回复。群机器人 Webhook适合单向消息推送例如 WorkBuddy 定时把日报推送到企业微信群。在 WorkBuddy 里通常两种都会用到。自建应用用于接收指令群机器人用于主动推送通知。企业微信自建应用需要关注Corp ID企业的唯一标识AgentId 和 Secret应用的 Agent ID 和密钥Token 与 EncodingAESKey用于回调验签和消息加解密注意企业微信回调需要配置“可信IP”。如果 WorkBuddy 部署在云服务器上要提前把服务器公网 IP 加到可信 IP 列表里。3.3 WorkBuddy 的配置文件格式WorkBuddy 项目在根目录下通常有一个config目录里面存放不同渠道的配置。示例结构如下workbuddy/ ├─ config/ │ ├─ default.json │ ├─ feishu.json │ ├─ wecom.json │ └─ skill/ ├─ src/ ├─ skills/ ├─ package.json └─ README.mddefault.json是基础配置feishu.json和wecom.json分别保存飞书与企业微信相关配置。配置的核心思路是把不同渠道的密钥、回调地址、开关状态拆开放置方便独立维护。{ app: { name: workbuddy-demo, port: 3000 }, log: { level: info } }注意任何包含 Secret 的配置文件都不要提交到 Git 仓库。建议使用环境变量或本地的.env文件来管理敏感信息。4. 快速把 WorkBuddy 跑起来4.1 方式一Docker 部署推荐新手如果你已经有 Docker 环境用 Docker 是最省心的方式。# 拉取项目源码 git clone https://github.com/your-workbuddy-repo/workbuddy.git cd workbuddy # 复制环境变量文件 cp .env.example .env # 使用 docker-compose 启动 docker compose up -d启动后访问http://localhost:3000如果能看到 WorkBuddy 的控制台页面说明基础服务已经正常运行。4.2 方式二源码方式运行# 安装依赖 pnpm install # 启动开发模式 pnpm dev源码方式更适合开发者二次调试。你可以实时修改 Skill 代码保存后热更新。4.3 验证服务状态启动完成后检查一下基础接口是否正常curl http://localhost:3000/api/health如果配置正确会返回类似下面的 JSON{ status: ok, version: 0.1.0 }到这里WorkBuddy 本身的骨架已经跑通了。接下来是重头戏连接飞书和企业微信。5. 实战案例把 WorkBuddy 接入飞书这个章节我们从零开始把 WorkBuddy 接到飞书让它能接收飞书私聊消息并回复。5.1 在飞书开放平台创建应用登录飞书开放平台。选择“企业自建应用”点击“创建应用”。填写应用名称和描述名称建议使用“WorkBuddy 助手”之类的名字。创建完成后在“凭证与基础信息”页面记录App ID和App Secret。接着在“添加应用能力”中开通“机器人”。5.2 配置权限和事件订阅进入“权限管理”页面搜索并开通以下权限im:message读取与发送用户消息im:message.group_at_msg读取群聊中 机器人的消息contact:user.base:readonly读取用户基本信息可选用于显示用户名然后在“事件与回调”页面添加事件im.message.receive_v1接收消息事件你需要提供一个 HTTPS 回调地址。格式为https://你的域名/webhook/feishu回调地址必须可以在公网访问。本地开发阶段可以用 ngrok 之类的内网穿透工具临时暴露一个地址但生产环境必须使用正式域名。5.3 修改飞书配置文件编辑config/feishu.json{ appId: cli_xxxxxxxxxxxxxxx, appSecret: 你的 App Secret, eventEncryptKey: , verificationToken: , callbackUrl: /webhook/feishu, receiveIdType: open_id }说明appId飞书应用的 App IDappSecret飞书应用的 App SecreteventEncryptKey如果你在飞书后台开启了 Encrypt Key这里要填写没开启就留空verificationToken事件订阅里的 Verification Token没开启也留空receiveIdType接收消息时的用户 ID 类型推荐使用open_id5.4 编写飞书回显 Skill在skills/目录下新建feishu_echo文件夹创建index.js和skill.json{ name: feishu_echo, description: 回显飞书用户发送的内容用于测试消息链路是否连通, triggerType: message, matchRule: keyword, matchValue: echo }// 文件路径skills/feishu_echo/index.js module.exports async function (ctx) { const { text, sender } ctx.message; return { content: 你说的是${text}\n来自${sender.openId} }; };这是一个最简单的 Skill作用是当用户发送echo 你好时机器人回复你说的是你好。5.5 启动并测试飞书链路pnpm dev然后打开飞书找到你创建的这个应用发送echo 你好飞书正常情况下你会收到机器人的回复你说的是你好飞书 来自ou_xxxxxxxxxxxxxxxxx到这里WorkBuddy 和飞书的消息链路已经完整跑通。5.6 让飞书能创建待办任务下面演示一个更实用的场景通过飞书消息创建待办。新建skills/feishu_todo{ name: feishu_todo, description: 把用户发送的内容创建为飞书待办, triggerType: message, matchRule: prefix, matchValue: 待办 }// 文件路径skills/feishu_todo/index.js const axios require(axios); module.exports async function (ctx) { const { text } ctx.message; const todoTitle text.replace(/^待办[:]?\s*/, ).trim(); if (!todoTitle) { return { content: 请按照「待办内容」的格式发送消息。 }; } const { appId, appSecret } ctx.config.feishu; // 1. 获取 tenant_access_token const tokenRes await axios.post(https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal, { app_id: appId, app_secret: appSecret }); const accessToken tokenRes.data.tenant_access_token; // 2. 调用待办接口创建任务 const todoRes await axios.post( https://open.feishu.cn/open-apis/task/v2/tasks, { summary: todoTitle, due: { timestamp: Math.floor(Date.now() / 1000) 24 * 3600 } }, { headers: { Authorization: Bearer ${accessToken}, Content-Type: application/json } } ); return { content: 已创建飞书待办${todoTitle} }; };测试方法待办本周五前完成项目复盘文档机器人会创建一条待办并回复确认消息。需要注意创建待办接口需要额外开通权限。可以在飞书开放平台的“权限管理”中搜索task相关权限比如task:task。没有权限时接口会返回permission denied。5.7 飞书多维表格如何配合很多同学会问“能不能把 WorkBuddy 收到的消息直接写入飞书多维表格”可以而且这是很常见的用法。原理是通过飞书多维表格开放接口把消息内容作为记录追加到指定数据表。由于多维表格的数据表 ID、视图 ID 都需要从表格 URL 中提取建议先手动创建一个简单的数据表再让 WorkBuddy 写入。步骤在飞书多维表格中新建一个表字段包括“来源用户”“消息内容”“接收时间”。在 WorkBuddy 中写一个新的 Skill调用多维表格接口追加记录。每收到一条关键词消息就写入一行。思路和上面待办任务完全一致区别只是接口换成多维表格记录接口。如果你项目里正好需要做“客服消息自动归档”这个组合会很实用。6. 实战案例把 WorkBuddy 接入企业微信企业微信的接入方式与飞书略有不同。下面重点展示两种能力接收员工消息并自动回复、定时向群聊推送通知。6.1 创建企业微信自建应用登录企业微信管理后台。选择“应用管理” - “自建” - “创建应用”。填写应用名称、可见范围。可见范围建议先选一个测试部门避免影响全员。创建完成后在“企业信息”中获取Corp ID在应用详情页获取AgentId和Secret。6.2 配置接收消息服务器在企业微信应用详情页找到“接收消息”设置填写URLhttps://你的域名/webhook/wecomToken随机字符串用于签名验证EncodingAESKey随机密钥用于消息加密然后在 WorkBuddy 的config/wecom.json中保存对应配置{ corpId: ww1234567890, agentId: 1000002, secret: 你的应用 Secret, token: 你的回调 Token, encodingAESKey: 你的 EncodingAESKey, callbackUrl: /webhook/wecom }这里最重要的一个点是WorkBuddy 服务必须能正确解密企业微信发来的加密消息。如果Token或EncodingAESKey配置错误回调 URL 在验证阶段就会失败。6.3 编写企微自动回复 Skill{ name: wecom_reply, description: 回复企业微信用户消息返回当前时间, triggerType: message, matchRule: keyword, matchValue: 时间 }// 文件路径skills/wecom_reply/index.js module.exports async function (ctx) { const now new Date(); const timeStr ${now.getFullYear()}-${now.getMonth() 1}-${now.getDate()} ${now.getHours()}:${now.getMinutes()}:${now.getSeconds()}; return { content: 当前时间是${timeStr} }; };在企微中给自建应用发消息时间应用会回复当前时间是2025-01-15 14:30:226.4 企业微信群机器人消息推送除了自建应用很多人还会用“群机器人 Webhook”做定时通知。在企业微信群中点击右键 - 添加群机器人复制 Webhook 地址。然后写一个定时推送的 Skill 或脚本// 文件路径skills/wecom_notify/index.js const axios require(axios); module.exports async function (ctx) { const webhookUrl ctx.config.wecom.groupBotWebhook; const content 大家好这是 WorkBuddy 定时推送的日报信息。; await axios.post(webhookUrl, { msgtype: text, text: { content } }); return { content: 群通知推送成功 }; };通过配置定时触发你可以实现“每天早上 9 点推送待办汇总”“每周五下午推送周报提醒”等自动化能力。6.5 企业微信接入 DeepSeek 等模型这里补充说明一个热词场景“企业微信接入 DeepSeek”。WorkBuddy 本身是消息调度中枢对接 DeepSeek 或 OpenAI 兼容 API 也非常容易。你只需要在回复逻辑中调用模型接口即可// 文件路径skills/ai_chat/index.js const axios require(axios); module.exports async function (ctx) { const { text } ctx.message; const res await axios.post(https://api.deepseek.com/v1/chat/completions, { model: deepseek-chat, messages: [ { role: system, content: 你是一个企业内部助理助手。 }, { role: user, content: text } ] }, { headers: { Authorization: Bearer ${process.env.DEEPSEEK_API_KEY} } }); return { content: res.data.choices[0].message.content }; };这样一来员工在企业微信里提问WorkBuddy 会把问题转发给大模型再把结果返回。企业微信和大模型的能力就这样打通了。需要注意调用外部大模型 API 时一定要处理好敏感信息。不要将企业内部的机密文档直接拼进 prompt建议做脱敏处理。7. 常见问题与排查思路这一部分是我在实操中反复踩过的坑整理出来给大家参考。问题现象常见原因解决思路飞书消息事件接收不到回调地址不合法 / 没加事件订阅检查回调 URL 是否公网可达确认后台已添加im.message.receive_v1飞书发送消息时报permission denied未开通对应 API 权限到飞书开放平台开通权限等待 1-2 分钟生效企微回调验证失败Token 或 EncodingAESKey 不一致确认 WorkBuddy 配置与企微后台完全一致注意不要有多余空格企微消息能收到但回复失败机器人回复需要调用主动发送接口检查agentId是否正确确认 Secret 归属该应用回调接口一直返回 500回调地址路径和代码路由不一致确认config/feishu.json中 callbackUrl 与代码注册路由一致部署在服务器后无法访问控制台端口未放行或绑定 127.0.0.1确认服务监听0.0.0.0并在防火墙放行对应端口启动时报 Redis 连接错误Redis 未启动或地址错误检查 Redis 服务状态配置为空则关闭对应插件定时任务没有触发时区设置不对检查服务器时区建议设置为Asia/Shanghai代码修改后不生效进程未重启确认是否热更新成功必要时手动重启服务日志中频繁出现 token 过期Secret 重置后旧配置仍在生效重新获取 Secret并更新配置文件7.1 排查建议这里分享一个通用的消息链路排查顺序。遇到机器人不响应时按以下顺序确认消息有没有到 WorkBuddy 服务看服务日志有没有收到回调请求Skill 有没有命中看匹配规则关键词、前缀是否写对执行过程有没有报错看日志中的错误堆栈结果有没有返回给 IM 平台看消息接口调用是否成功大多数问题都能在前两步定位到。如果服务日志中连请求都没有优先检查回调地址、公网可达性和事件订阅。8. 工程化建议与最佳实践把 WorkBuddy 接起来只是第一步。真正把它用在生产环境中还要考虑稳定性、安全性和可维护性。8.1 环境变量管理不要在配置文件里写明文密钥。推荐方案# .env 文件加入 .gitignore FEISHU_APP_IDcli_xxxx FEISHU_APP_SECRETxxxx WECOM_CORP_IDwwxxxx WECOM_AGENT_ID1000002 WECOM_SECRETxxxx DEEPSEEK_API_KEYsk-xxxx然后在代码中通过process.env读取const appId process.env.FEISHU_APP_ID;这样即使代码仓库泄露也不会把密钥一起暴露出去。8.2 日志与追踪每条消息建议记录以下信息渠道类型feishu / wecom用户 ID消息内容注意脱敏命中的 Skill处理耗时执行结果日志格式可以使用 JSON方便后续接入日志分析平台。同时建议为每次消息处理生成一个requestId方便追踪整条调用链。8.3 限流与权限控制生产环境必须考虑安全边界敏感操作二次确认删除、审批、转账类行为机器人回复用户确认收到明确确认消息后才执行。IP 白名单如果 WorkBuddy 只服务内部员工可以限制飞书/企微回调来源 IP 或校验签名。接口限流防止恶意频繁调用外部 API导致上游限流。最小权限原则飞书和企业微信应用的权限只开当前需要的不要全都勾选。8.4 部署与监控生产环境推荐使用 systemd 或 Docker 管理 WorkBuddy 进程。如果任务比较多建议接入Uptime Kuma之类的监控工具定时探测健康检查接口。一旦 WorkBuddy 下线可以立即通过飞书或企微收到告警。巧妙的是WorkBuddy 本身就能接入飞书和企微你完全可以做一个自监控的 Skill定期调用健康检查接口发现异常时主动推送消息到群聊。8.5 Skill 设计原则写 Skill 时尽量保持“单一职责”。一个 Skill 只做一件事feishu_todo只负责创建待办wecom_reply只负责回复时间ai_chat只负责调用模型不要把多个逻辑塞进一个 Skill。后续要加能力就新增 Skill而不是在旧 Skill 里堆 if-else。9. 学习路线与下一步建议到这里WorkBuddy 的核心链路已经全部跑通了。回顾一下这篇文章的收获理解 WorkBuddy 的 Agent、Skill、Channel、Task 四层基本架构。在本地或服务器上成功部署 WorkBuddy。在飞书开放平台创建自建应用接入消息事件实现私聊回复和待办创建。在企业微信中创建自建应用和群机器人实现双向消息与定时推送。掌握了消息链路排查方法和常见错误处理。接下来你可以继续探索的方向9.1 深化技能开发目前我们写的 Skill 都是最简单的同步逻辑。深入研究后可以尝试异步 Skill将耗时操作放到队列中通过回调或主动推送返回结果。多轮对话 Skill维护会话上下文实现连续对话。工具调用模式让 Agent 自动判断该调用哪个 Skill 来处理用户输入。9.2 场景模板复用企业在实际使用时往往有很多重复场景。比如请假审批员工在飞书发送“请假一天”WorkBuddy 先生成审批表单再推送给主管。日报汇总每天晚上自动收集成员日报汇总后推送到企业微信群。知识库问答把内部知识文档接入向量库员工通过 IM 直接检索。这些场景本质上都是走通一条相似路径消息接收 - 意图解析 - 调用业务接口 - 返回结果。一旦你理解了 Skill 的编写方式就能快速扩展。9.3 关注官方更新WorkBuddy 目前还在快速迭代中社区也比较活跃。建议多关注 GitHub 仓库的 release 和文档更新了解新版本的 API 变化。开源项目的特性是演进速度快如果项目中使用了特定版本升级时一定要先看 changelog。9.4 参与开源共建如果你已经掌握了 WorkBuddy 的基本用法可以考虑给社区贡献 Skill 或修复问题。开源项目最需要的往往不是复杂的架构设计而是“真实的业务场景 优雅的解决方案”。你自己踩过的坑很可能就是别人正在踩的坑。写在最后WorkBuddy 最吸引我的地方是它把飞书、企业微信这类高频办公入口和 AI 能力连接了起来。它不是一个只能聊天的玩具而是一个能帮你真正处理任务的框架。这篇文章从零开始把部署、飞书接入、企业微信接入、Skill 开发、常见排查、工程规范全部过了一遍。如果你跟着操作一遍应该已经拥有一个属于你自己的“飞书 企业微信 AI 助理”了。后续我会继续更新 WorkBuddy 的进阶内容比如多轮对话设计、知识库集成、复杂审批流程等。如果你在配置过程中遇到问题欢迎在评论区留言我会尽量帮助你排查。也欢迎大家收藏本文方便下次操作时快速查阅。