之前一直在琢磨怎么把大模型能力真正落到公司的日常办公流里。飞书里的周报、审批、消息通知企业微信里的任务待办、客户群发、告警推送这些场景如果每个都单独开发一套机器人工作量并不小而且维护成本很高。最近看到 WorkBuddy 这套开源方案后我把它完整跑了一遍整理了这篇零基础教程覆盖从安装、配置飞书、配置企业微信到开发 Skill、接入模型、生产部署的内容。整套学习路径里能看到我实际踩过的坑和对应的排查方法不管是刚接触 AI Agent 的新手还是已经在做办公自动化的开发同学都可以照着操作。1. 背景与核心概念1.1 WorkBuddy 是什么办公协同里的 AI AgentWorkBuddy 可以理解为“办公场景下的 AI 数字员工”它做的事情是把大模型的对话能力、工具调用能力和飞书、企业微信这些日常办公软件连接到一起。专业一点的描述是WorkBuddy 是一个以 Agent 为核心的办公协同中间件。它在底层对接大模型 API在业务层提供消息接收与回复、任务待办、表格操作、事件回调等能力让用户不再需要打开一个个后台系统直接在 IM 里就能完成信息查询和任务处理。可以用下面这张图来理解它的定位大模型 APIDeepSeek、OpenAI、通义等 ↑ WorkBuddy Agent 引擎 ↑ 飞书消息 / 企业微信消息 / Webhook / 事件回调在飞书群聊里 机器人的时候WorkBuddy 会收到事件然后根据配置好的 Skill 决定调用哪个工具、给模型传什么上下文最后把结果回复到群里。整个过程对用户来说只有“发消息”和“收回复”两个动作。1.2 为什么需要打通飞书和企业微信很多公司并不是只用一款办公软件。研发团队可能用飞书管理项目销售客服团队可能用企业微信维护客户。如果 AI 助手只能接入其中一个就会出现信息孤岛。打通飞书和企业微信核心价值有几点统一处理入口用户不需要登录额外平台在 IM 对话里就能完成任务。消息双向流转飞书里的审批提醒可以通过机器人转发到企业微信企业微信里的任务进度也能同步回飞书。减少重复开发一套 Agent 逻辑通过不同适配器接入多个 IM。任务可闭环AI 不是只回复一句话而是真的去创建待办、写多维表格、推送消息。实际项目中最常见的使用方式是把 WorkBuddy 部署在一台服务器上飞书和企业微信分别是它的两个“频道”。同一个 Agent 引擎可以同时服务两个平台里的不同群组和用户。1.3 WorkBuddy 与 CodeBuddy 的定位区别很多人在搜索 WorkBuddy 时会同时看到 CodeBuddy这两个名字容易混淆。简单来说CodeBuddy 更偏向代码场景定位是 AI 编程助手能辅助写代码、改 bug、做 Code Review。WorkBuddy 更偏向办公和业务场景定位是 AI 工作助手重点处理消息、任务、表格、流程类操作。实际选型时如果是让 AI 帮你写代码用 CodeBuddy 更合适如果是让 AI 帮你在飞书群里管理待办、汇总日报、推送告警WorkBuddy 更对口。两者不是竞争关系而是场景互补。1.4 这套开源教程覆盖哪些内容我整理的开源教程一共 10 节从零开始目标是让一个没有接触过 AI Agent 的开发者也能完整跑通项目WorkBuddy 快速上手与整体架构源码本地搭建与调试技巧飞书自建应用创建与消息推送企业微信自建应用与事件回调核心 Agent 原理消息如何被处理Skill 机制详解飞书多维表格自动化实战任务待办与工作流自动化接入 DeepSeek 等大模型生产环境部署、日志与维护每节课都配套可运行的代码和配置文档下面我用实操的形式带大家完整走一遍其中最关键的部分。2. 环境准备与源码安装2.1 运行环境建议WorkBuddy 本质上是一个 Node.js 服务推荐环境如下项目建议配置操作系统Linux / macOS / Windows 均可生产建议 Ubuntu 22.04Node.js18 及以上版本包管理器pnpm 或 npm数据库SQLite 可用于本地体验生产建议 MySQL / PostgreSQL内存2GB 以上网络服务器需能访问飞书和企业微信开放接口这里有一个容易忽略的点如果是本地开发飞书和企业微信的服务器需要能访问到你的回调地址。本地调试时推荐使用内网穿透工具生成临时公网地址再填到飞书或企业微信后台。2.2 获取开源代码WorkBuddy 的开源代码主要通过 GitHub 分发。搜索“WorkBuddy 开源项目”可以找到仓库地址。拿到代码后先确认目录结构git clone workbuddy-repo-url cd workbuddy项目根目录一般会包含以下内容workbuddy/ ├── docs/ # 文档目录 ├── packages/ │ ├── core/ # 核心 Agent 逻辑 │ ├── adapter-feishu/ # 飞书适配器 │ ├── adapter-wecom/ # 企业微信适配器 │ └── server/ # HTTP 服务 ├── examples/ # 示例配置 ├── .env.example # 环境变量模板 └── package.json不同版本结构可能有差异但核心目录基本一致。docs 目录里的内容就是开源教程的配套文档。2.3 安装依赖并启动以 pnpm 为例在项目根目录执行# 安装依赖 pnpm install # 复制环境变量模板 cp .env.example .env # 启动开发模式 pnpm dev如果需要构建生产版本可以执行pnpm build pnpm start启动成功后终端会输出服务监听端口和已加载的适配器列表。如果没有任何报错说明本地基础环境已经跑通。在继续之前建议先确认 .env 文件里已经配置好基础项# 服务端口 PORT3000 # 日志级别 LOG_LEVELinfo # 数据存储方式 DB_DRIVERsqlite2.4 安装后的检查项安装完成并不代表能正常工作建议按下面的顺序做一次健康检查服务端口是否正常监听curl http://localhost:3000/health控制台输出是否包含“adapter loaded”之类的日志。数据库文件是否生成SQLite 模式下根目录会出现 workbuddy.db。查看 docs/quickstart.md 文档确认当前版本是否有额外依赖。这一步顺利通过后就可以开始接入飞书和企业微信了。3. 接入飞书应用创建与消息推送3.1 飞书开放平台的接入前提在飞书中接入 WorkBuddy实质上是把 WorkBuddy 注册成飞书开放平台里的一个“企业自建应用”并开启“机器人”能力。飞书的开放接口文档里有三类常用的权限发送消息im:message、im:message:send_as_bot读取用户信息contact:user.base:readonly操作多维表格bitable:app、bitable:app:readonly官方文档对权限名更新较频繁建议在飞书开放平台后台的“权限管理”页面直接搜索功能关键词例如“发送消息”“读取用户”等再根据提示开通对应权限。3.2 创建企业自建应用具体步骤我按照飞书开放平台的通常流程整理登录飞书开放平台进入“开发者后台”。选择企业点击“创建企业自建应用”。填写应用名称和描述例如“WorkBuddy 办公助手”。创建完成后进入“应用能力”模块开启“机器人”能力。进入“权限管理”添加消息发送、文件上传、多维表格等权限。进入“版本管理与发布”创建版本并申请发布上线。这一步在企业内部使用时通常需要管理员审批。发布成功后在“凭证与基础信息”页面可以拿到两个关键参数App IDApp Secret这两个参数会用在 WorkBuddy 的飞书适配器配置里。3.3 用 Webhook 快速验证消息通道在配置复杂的回调之前先用自定义机器人 Webhook 验证消息通道是否畅通。飞书自定义机器人是群聊里的一个 Webhook 地址向它发送 POST 请求就能在群里收到一条机器人消息。 文件路径examples/feishu_webhook.py 功能向飞书群聊发送文本消息 用法python feishu_webhook.py import requests import json def send_feishu_webhook(webhook_url: str, text: str): 推送飞书文本消息 :param webhook_url: 飞书自定义机器人 Webhook 地址 :param text: 要发送的文本内容 headers { Content-Type: application/json } payload { msg_type: text, content: { text: text } } response requests.post(webhook_url, headersheaders, datajson.dumps(payload)) print(HTTP 状态码:, response.status_code) print(响应内容:, response.text) if __name__ __main__: url https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_URL send_feishu_webhook(url, WorkBuddy 飞书通道测试消息)如果消息成功出现在群里说明网络链路是通的。Webhook 方式适合做简单告警通知但它的功能有限无法实现双向对话。要实现复杂的 Agent 能力还是需要配置事件订阅和机器人应用。3.4 在 WorkBuddy 中配置飞书连接在 WorkBuddy 的环境变量或配置文件中飞书适配器通常需要以下配置# 飞书应用凭证 FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETyour_app_secret # 事件订阅回调路径 FEISHU_EVENT_ENDPOINT/feishu/event # 加密和解密用的 Encrypt Key FEISHU_ENCRYPT_KEYyour_encrypt_key # 验证用的 Verification Token FEISHU_VERIFICATION_TOKENyour_verification_token配置完成后需要到飞书开放平台后台填写“事件订阅”的回调地址。回调地址格式为http://你的公网域名或IP/feishu/event在飞书后台点击“订阅事件”添加机器人接收消息事件。保存时飞书会发送一个 URL 验证请求WorkBuddy 会返回加密串完成校验。验证通过后重启 WorkBuddy再向机器人发送一条“你好”如果返回正常飞书接入就完成了。4. 接入企业微信应用创建与主动消息4.1 企业微信自建应用创建流程接入企业微信的思路和飞书类似但后台入口和参数名称不同。企业微信里WorkBuddy 本质上是一个“自建应用”。创建步骤如下登录企业微信管理后台。进入“应用管理” “应用” “自建应用”。点击“创建应用”上传应用 Logo填写应用名称。创建完成后能看到 AgentId 和 Secret。配置“企业可信 IP”把 WorkBuddy 所在服务器的公网 IP 加入白名单。在“接收消息”中填写回调 URL用于接收用户的文本消息和服务端事件。另外企业微信里有一个全局参数 CorpID也就是企业 ID。在管理后台“我的企业”页面可以找到。企业微信接口调用需要三个关键参数CorpID企业唯一标识。AgentId自建应用的 Agent ID。Secret自建应用的密钥。4.2 获取企业微信 Webhook 并发送测试消息和飞书一样企业微信也有群机器人 Webhook适合快速验证消息通道。在某个企业微信群中点击右上角“群设置” “群机器人” “添加机器人”就可以生成一个 Webhook 地址。 文件路径examples/wecom_webhook.py 功能向企业微信群聊发送文本消息 用法python wecom_webhook.py import requests import json def send_wecom_webhook(webhook_url: str, content: str): 推送企业微信文本消息 :param webhook_url: 企业微信机器人 Webhook 地址 :param content: 发送的文本内容 headers { Content-Type: application/json } payload { msgtype: text, text: { content: content } } response requests.post(webhook_url, headersheaders, datajson.dumps(payload)) print(HTTP 状态码:, response.status_code) print(响应内容:, response.text) if __name__ __main__: url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyYOUR_KEY send_wecom_webhook(url, WorkBuddy 企业微信通道测试消息)如果群内收到消息说明企业微信的 Webhook 通道正常。4.3 通过 access_token 发送应用消息Webhook 只能发消息到配置了机器人的群而应用消息可以主动推送给指定用户适合做任务提醒、审批通知。调用企业微信 API需要先获取 access_token然后调用 message/send 接口。 文件路径examples/wecom_send_app_message.py 功能通过企业微信应用向指定用户发送文本消息 import requests def get_access_token(corp_id: str, corp_secret: str) - str: 获取企业微信 access_token url https://qyapi.weixin.qq.com/cgi-bin/gettoken params { corpid: corp_id, corpsecret: corp_secret } response requests.get(url, paramsparams) data response.json() if data.get(errcode) ! 0: raise RuntimeError(f获取 access_token 失败: {data}) return data[access_token] def send_text_message(access_token: str, agent_id: int, user_ids: str, content: str): 向指定用户发送应用消息 :param access_token: 企业微信 access_token :param agent_id: 自建应用 AgentId :param user_ids: 用户 UserID多个用 | 分隔 :param content: 文本内容 url https://qyapi.weixin.qq.com/cgi-bin/message/send params { access_token: access_token } payload { touser: user_ids, msgtype: text, agentid: agent_id, text: { content: content } } response requests.post(url, paramsparams, jsonpayload) data response.json() if data.get(errcode) ! 0: raise RuntimeError(f消息发送失败: {data}) print(消息发送成功:, data) if __name__ __main__: corp_id 你的企业ID corp_secret 你的应用Secret agent_id 1000002 token get_access_token(corp_id, corp_secret) send_text_message(token, agent_id, zhangsan, WorkBuddy 应用消息测试)这里的关键点是access_token 有效期是 7200 秒应该做缓存不要每次都请求。企业可信 IP 没有配置时接口会返回60020错误。UserID 不是手机号或姓名需要在企业微信通讯录里查看。4.4 在 WorkBuddy 中配置企业微信连接WorkBuddy 的企业微信适配器配置同样放在环境变量或配置文件中# 企业微信凭证 WECOM_CORP_IDyour_corp_id WECOM_AGENT_ID1000002 WECOM_SECRETyour_wecom_secret # 回调服务 WECOM_CALLBACK_URL/wecom/callback WECOM_TOKENyour_callback_token WECOM_ENCODING_AES_KEYyour_encoding_aes_key企业微信的回调机制比飞书更繁琐一些需要配置 Token 和 EncodingAESKey。保存回调 URL 后需要点击“保存”企业微信会向该地址发送一个验证请求。WorkBuddy 如果已经实现了适配器逻辑会自动完成签名校验和明文解密。整体流程完成后你可以在企业微信中给自建应用发一条消息正常情况下 WorkBuddy 会给出回复。5. 实战案例用飞书多维表格做任务管理5.1 案例需求与设计假设业务场景是这样的每天销售团队会把跟进客户的情况发到飞书群里我们希望 WorkBuddy 在飞书群里收到消息后自动把消息里的客户名称、跟进人、销售阶段写入一张多维表格。这个案例涉及三层能力飞书机器人接收群消息。解析自然语言文本。调用多维表格 API 写入数据。先准备好一张多维表格或者让 WorkBuddy 通过 API 自动创建。下面演示如何用 Python 调用飞书多维表格 API。5.2 创建多维表格调用飞书 API 前需要先获取 tenant_access_token它是应用级别访问凭证。 文件路径examples/feishu_tenant_token.py 功能获取飞书 tenant_access_token import requests import json def get_tenant_access_token(app_id: str, app_secret: str) - str: url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal headers { Content-Type: application/json } payload { app_id: app_id, app_secret: app_secret } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f获取 tenant_access_token 失败: {data}) return data[tenant_access_token]拿到 token 后创建表格。飞书多维表格的字段类型中1 表示文本3 表示单选。 文件路径examples/feishu_create_table.py 功能在多维表格中创建数据表 import requests import json def create_table(tenant_access_token: str, app_token: str, table_name: str): url fhttps://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables headers { Authorization: fBearer {tenant_access_token}, Content-Type: application/json } payload { table: { name: table_name, fields: [ { field_name: 客户名称, type: 1 }, { field_name: 跟进人, type: 1 }, { field_name: 销售阶段, type: 3, property: { options: [ {name: 初步沟通}, {name: 方案演示}, {name: 商务谈判}, {name: 已成交} ] } } ] } } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f创建数据表失败: {data}) print(数据表创建成功, data[data][table_id])其中app_token是多维表格应用的 token在飞书多维表格 URL 里可以看到。5.3 写入与更新记录创建完表之后就可以在收到群消息时调用写入接口。 文件路径examples/feishu_add_record.py 功能向多维表格数据表添加一条记录 import requests import json def add_record(tenant_access_token: str, app_token: str, table_id: str, customer: str, owner: str, stage: str): url fhttps://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records headers { Authorization: fBearer {tenant_access_token}, Content-Type: application/json } payload { fields: { 客户名称: customer, 跟进人: owner, 销售阶段: stage } } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f写入记录失败: {data}) print(记录写入成功record_id:, data[data][record][record_id])这样一条客户跟进记录就自动进了多维表格。团队在飞书群里说的内容会沉淀成结构化数据后续可以再接入 BI 工具做统计。5.4 将表格操作封装成 WorkBuddy Skill上面的 Python 脚本可以直接用但在 WorkBuddy 中更推荐把这类操作封装成 Skill这样 Agent 才能自动决定何时调用。WorkBuddy 中一个 Skill 通常包含名称、描述、触发方式和可执行工具。下面用常见的 JSON 风格做一个示例具体字段以你使用的版本文档为准{ name: feishu_customer_tracking, description: 当用户提供客户名称、跟进人和销售阶段信息时写入飞书多维表格客户跟进表, trigger: { type: keyword, keywords: [客户, 跟进, 销售阶段] }, tools: [ { name: feishu.bitable.add_record, config: { app_token: your_app_token, table_id: your_table_id } } ] }之后在飞书群里发送“新增客户某某科技跟进人张三阶段方案演示”WorkBuddy 就会匹配到这个 Skill调用表格写入工具并回复“已记录”给群聊。6. 进阶模型接入与任务待办自动化6.1 在 WorkBuddy 中配置大模型WorkBuddy 的对话能力依赖底层大模型。目前国内外主流模型都有兼容方案可以通过配置模型供应商名和 API Key 接入。在配置文件中通常会有类似这样的配置MODEL_PROVIDERdeepseek MODEL_API_KEYyour_deepseek_api_key MODEL_NAMEdeepseek-chat MODEL_TEMPERATURE0.3接入 DeepSeek 时需要注意API Key 是敏感信息不要提交到 git 仓库。生产环境建议通过环境变量注入而不是写死在文件里。模型名称请以 DeepSeek 官方文档为准不同时期命名可能不同。6.2 企业微信任务待办示例在企业微信中把智能助手接入任务待办是很常见的需求。结合前文的应用消息 API我们可以做一个简单的“日报提醒”流程每天 18:00 触发定时任务。WorkBuddy 询问未提交日报的员工。员工把日报内容直接发给应用。WorkBuddy 调用消息发送接口回复确认信息。这个流程的关键代码如下import requests import json def send_template_card(access_token: str, agent_id: int, user_id: str, task_content: str): 向用户发送模板卡片消息 url https://qyapi.weixin.qq.com/cgi-bin/message/send params {access_token: access_token} payload { touser: user_id, msgtype: template_card, agentid: agent_id, template_card: { card_type: text_notice, source: { icon_url: , desc: WorkBuddy 日报提醒 }, main_title: { title: 今日待办提醒 }, horizontal_content_list: [ { keyname: 任务名称, value: task_content } ], card_action: { type: 1, url: https://example.com } } } response requests.post(url, paramsparams, jsonpayload) print(response.json())模板卡片比纯文本消息的展示效果更好适合待办、审批、通知类场景。6.3 待办自动化的建议任务待办自动化最容易出错的地方是“重复执行”和“错误处理”。建议在实现时考虑幂等性同一条待办被重复推送时不要产生重复记录。超时处理调用模型超时后要记录日志并进入重试队列。人工确认高风险的自动执行动作比如删除记录、发送外发消息应当设置人工确认环节。权限隔离不同部门的 Agent Skill 应有不同的数据访问范围。7. 常见问题与排查思路7.1 问题排查表格下面是我在搭建和运行过程中遇到的高频问题整理成表格方便快速定位问题现象常见原因解决思路飞书事件订阅验证失败回调地址无法访问或 Encrypt Key 配置错误确认服务器公网可达检查 Encrypt Key 和 Verification Token飞书机器人不回复群消息没有订阅 im.message.receive_v1 事件在飞书后台重新订阅事件并确认版本已发布上线企业微信应用消息报错 60020服务器 IP 未加入企业可信 IP在自建应用配置中添加入口服务器的公网 IP企业微信 access_token 获取失败CorpID 或 Secret 填写错误核对管理后台参数注意 Secret 中不可有空格发送消息报错 40058参数格式不正确检查 touser、msgtype、agentid 是否有缺失大模型接口超时网络不稳定或模型服务繁忙增加超时时间配置重试和熔断表格数据写入失败但接口返回 0App Token 或 Table ID 不对检查多维表格 URL 中的 app_token 和 table_id数据库锁相关报错并发写入压力大SQLite 不适合高并发生产环境切换 MySQL / PostgreSQL7.2 典型错误处理服务无法启动时第一步不是改代码而是看日志。WorkBuddy 一般会输出每个适配器的加载情况如果某个适配器配置缺失日志里会提示。排查顺序建议是检查环境变量是否加载完整。检查端口是否被占用。检查数据库连接是否可用。检查回调地址是否能从公网访问。检查对应平台后台的权限是否齐全。用最小复现方式调试比如先只用 Webhook 发一条消息。验证消息链路时可以先用最简单的 Webhook 脚本确认网络再逐个增加复杂度不要一上来就调试完整 Agent 流程。8. 最佳实践与工程建议8.1 权限与密钥管理密钥管理是这类项目最容易出安全问题的点。App Secret、API Key 都是敏感凭据不要提交到代码仓库。建议使用环境变量或者专业的密钥管理服务。在 .env.example 中使用占位符而不是真实值。给飞书和企业微信应用分配最小权限只申请必要的权限范围不要图省事全选。8.2 消息频率与限流飞书和企业微信对消息 API 都有频率限制。当系统告警集中爆发时如果直接调用 API 推送会触发限流导致消息丢失。一个合适的方案是在 WorkBuddy 和 IM 平台之间加入简单队列。消息先进入队列再按固定速率推送队列积压时通过日志告警。8.3 多环境配置本地开发、测试、生产环境应使用不同的配置和不同的自建应用。我推荐的配置方式.env.local # 本地开发可关闭 HTTPS 校验 .env.test # 测试环境使用测试企业 .env.production # 生产环境使用正式飞书/企业微信应用8.4 日志与监控生产环境必须做好日志和监控。保存 WorkBuddy 运行日志至少保留 7 天。监控消息成功率连续失败时发送告警。监控回调接口响应时间建议 P95 小于 1 秒。监控模型 API 调用成本。如果线上出现消息不回复的情况最有效的排查手段是看“一条消息从 IM 进入 WorkBuddy 后走了哪个 Skill最终是否被消费”所以日志里一定要打印 trace_id 或 request_id。9. 总结与下一步学习路线9.1 10 节课程的学习路径到这里你已经了解 WorkBuddy 的安装、飞书接入、企业微信接入、多维表格实战、任务待办和部分排错思路。如果你想系统学习建议按我整理的 10 节开源课程顺序推进快速上手先跑通本地 demo。读懂源码结构知道每个包管什么。完成飞书机器人配置体验消息收和发。完成企业微信应用配置体验主动推送。理解 Agent 处理消息的完整链路。从现成 Skill 开始改再写自己的 Skill。用多维表格做数据沉淀。实现一个带状态的任务待办。接入 DeepSeek 或其他模型体验不同模型的效果差异。部署到公网服务器配置日志、监控和守护进程。每一步都可以在我整理的开源文档中找到对应的代码和配置示例。文档中缺失的细节建议结合平台官方 API 文档再核对因为飞书和企业微信的接口处于快速迭代期版本差异较大。9.2 继续精进的方向当你跑通基础流程后还可以继续扩展这些方向把 WorkBuddy 与内部接口对接当成统一 API 助手。结合 MCP 协议让 WorkBuddy 调用更多外部工具。加入定时触发能力做日报、周报自动生成。接入更多办公平台让一套 Agent 引擎服务多个业务系统。最后给你一个实用建议先从一个最小业务场景开始例如“把飞书群消息写入多维表格”跑通后再逐步叠加功能。不要把第一版设计得太复杂否则排错时会很难定位问题。如果这篇文章对你有帮助建议收藏备用动手实现时绝大多数步骤都能直接对照操作。
之前一直在琢磨怎么把大模型能力真正落到公司的日常办公流里。飞书里的周报、审批、消息通知企业微信里的任务待办、客户群发、告警推送这些场景如果每个都单独开发一套机器人工作量并不小而且维护成本很高。最近看到 WorkBuddy 这套开源方案后我把它完整跑了一遍整理了这篇零基础教程覆盖从安装、配置飞书、配置企业微信到开发 Skill、接入模型、生产部署的内容。整套学习路径里能看到我实际踩过的坑和对应的排查方法不管是刚接触 AI Agent 的新手还是已经在做办公自动化的开发同学都可以照着操作。1. 背景与核心概念1.1 WorkBuddy 是什么办公协同里的 AI AgentWorkBuddy 可以理解为“办公场景下的 AI 数字员工”它做的事情是把大模型的对话能力、工具调用能力和飞书、企业微信这些日常办公软件连接到一起。专业一点的描述是WorkBuddy 是一个以 Agent 为核心的办公协同中间件。它在底层对接大模型 API在业务层提供消息接收与回复、任务待办、表格操作、事件回调等能力让用户不再需要打开一个个后台系统直接在 IM 里就能完成信息查询和任务处理。可以用下面这张图来理解它的定位大模型 APIDeepSeek、OpenAI、通义等 ↑ WorkBuddy Agent 引擎 ↑ 飞书消息 / 企业微信消息 / Webhook / 事件回调在飞书群聊里 机器人的时候WorkBuddy 会收到事件然后根据配置好的 Skill 决定调用哪个工具、给模型传什么上下文最后把结果回复到群里。整个过程对用户来说只有“发消息”和“收回复”两个动作。1.2 为什么需要打通飞书和企业微信很多公司并不是只用一款办公软件。研发团队可能用飞书管理项目销售客服团队可能用企业微信维护客户。如果 AI 助手只能接入其中一个就会出现信息孤岛。打通飞书和企业微信核心价值有几点统一处理入口用户不需要登录额外平台在 IM 对话里就能完成任务。消息双向流转飞书里的审批提醒可以通过机器人转发到企业微信企业微信里的任务进度也能同步回飞书。减少重复开发一套 Agent 逻辑通过不同适配器接入多个 IM。任务可闭环AI 不是只回复一句话而是真的去创建待办、写多维表格、推送消息。实际项目中最常见的使用方式是把 WorkBuddy 部署在一台服务器上飞书和企业微信分别是它的两个“频道”。同一个 Agent 引擎可以同时服务两个平台里的不同群组和用户。1.3 WorkBuddy 与 CodeBuddy 的定位区别很多人在搜索 WorkBuddy 时会同时看到 CodeBuddy这两个名字容易混淆。简单来说CodeBuddy 更偏向代码场景定位是 AI 编程助手能辅助写代码、改 bug、做 Code Review。WorkBuddy 更偏向办公和业务场景定位是 AI 工作助手重点处理消息、任务、表格、流程类操作。实际选型时如果是让 AI 帮你写代码用 CodeBuddy 更合适如果是让 AI 帮你在飞书群里管理待办、汇总日报、推送告警WorkBuddy 更对口。两者不是竞争关系而是场景互补。1.4 这套开源教程覆盖哪些内容我整理的开源教程一共 10 节从零开始目标是让一个没有接触过 AI Agent 的开发者也能完整跑通项目WorkBuddy 快速上手与整体架构源码本地搭建与调试技巧飞书自建应用创建与消息推送企业微信自建应用与事件回调核心 Agent 原理消息如何被处理Skill 机制详解飞书多维表格自动化实战任务待办与工作流自动化接入 DeepSeek 等大模型生产环境部署、日志与维护每节课都配套可运行的代码和配置文档下面我用实操的形式带大家完整走一遍其中最关键的部分。2. 环境准备与源码安装2.1 运行环境建议WorkBuddy 本质上是一个 Node.js 服务推荐环境如下项目建议配置操作系统Linux / macOS / Windows 均可生产建议 Ubuntu 22.04Node.js18 及以上版本包管理器pnpm 或 npm数据库SQLite 可用于本地体验生产建议 MySQL / PostgreSQL内存2GB 以上网络服务器需能访问飞书和企业微信开放接口这里有一个容易忽略的点如果是本地开发飞书和企业微信的服务器需要能访问到你的回调地址。本地调试时推荐使用内网穿透工具生成临时公网地址再填到飞书或企业微信后台。2.2 获取开源代码WorkBuddy 的开源代码主要通过 GitHub 分发。搜索“WorkBuddy 开源项目”可以找到仓库地址。拿到代码后先确认目录结构git clone workbuddy-repo-url cd workbuddy项目根目录一般会包含以下内容workbuddy/ ├── docs/ # 文档目录 ├── packages/ │ ├── core/ # 核心 Agent 逻辑 │ ├── adapter-feishu/ # 飞书适配器 │ ├── adapter-wecom/ # 企业微信适配器 │ └── server/ # HTTP 服务 ├── examples/ # 示例配置 ├── .env.example # 环境变量模板 └── package.json不同版本结构可能有差异但核心目录基本一致。docs 目录里的内容就是开源教程的配套文档。2.3 安装依赖并启动以 pnpm 为例在项目根目录执行# 安装依赖 pnpm install # 复制环境变量模板 cp .env.example .env # 启动开发模式 pnpm dev如果需要构建生产版本可以执行pnpm build pnpm start启动成功后终端会输出服务监听端口和已加载的适配器列表。如果没有任何报错说明本地基础环境已经跑通。在继续之前建议先确认 .env 文件里已经配置好基础项# 服务端口 PORT3000 # 日志级别 LOG_LEVELinfo # 数据存储方式 DB_DRIVERsqlite2.4 安装后的检查项安装完成并不代表能正常工作建议按下面的顺序做一次健康检查服务端口是否正常监听curl http://localhost:3000/health控制台输出是否包含“adapter loaded”之类的日志。数据库文件是否生成SQLite 模式下根目录会出现 workbuddy.db。查看 docs/quickstart.md 文档确认当前版本是否有额外依赖。这一步顺利通过后就可以开始接入飞书和企业微信了。3. 接入飞书应用创建与消息推送3.1 飞书开放平台的接入前提在飞书中接入 WorkBuddy实质上是把 WorkBuddy 注册成飞书开放平台里的一个“企业自建应用”并开启“机器人”能力。飞书的开放接口文档里有三类常用的权限发送消息im:message、im:message:send_as_bot读取用户信息contact:user.base:readonly操作多维表格bitable:app、bitable:app:readonly官方文档对权限名更新较频繁建议在飞书开放平台后台的“权限管理”页面直接搜索功能关键词例如“发送消息”“读取用户”等再根据提示开通对应权限。3.2 创建企业自建应用具体步骤我按照飞书开放平台的通常流程整理登录飞书开放平台进入“开发者后台”。选择企业点击“创建企业自建应用”。填写应用名称和描述例如“WorkBuddy 办公助手”。创建完成后进入“应用能力”模块开启“机器人”能力。进入“权限管理”添加消息发送、文件上传、多维表格等权限。进入“版本管理与发布”创建版本并申请发布上线。这一步在企业内部使用时通常需要管理员审批。发布成功后在“凭证与基础信息”页面可以拿到两个关键参数App IDApp Secret这两个参数会用在 WorkBuddy 的飞书适配器配置里。3.3 用 Webhook 快速验证消息通道在配置复杂的回调之前先用自定义机器人 Webhook 验证消息通道是否畅通。飞书自定义机器人是群聊里的一个 Webhook 地址向它发送 POST 请求就能在群里收到一条机器人消息。 文件路径examples/feishu_webhook.py 功能向飞书群聊发送文本消息 用法python feishu_webhook.py import requests import json def send_feishu_webhook(webhook_url: str, text: str): 推送飞书文本消息 :param webhook_url: 飞书自定义机器人 Webhook 地址 :param text: 要发送的文本内容 headers { Content-Type: application/json } payload { msg_type: text, content: { text: text } } response requests.post(webhook_url, headersheaders, datajson.dumps(payload)) print(HTTP 状态码:, response.status_code) print(响应内容:, response.text) if __name__ __main__: url https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_URL send_feishu_webhook(url, WorkBuddy 飞书通道测试消息)如果消息成功出现在群里说明网络链路是通的。Webhook 方式适合做简单告警通知但它的功能有限无法实现双向对话。要实现复杂的 Agent 能力还是需要配置事件订阅和机器人应用。3.4 在 WorkBuddy 中配置飞书连接在 WorkBuddy 的环境变量或配置文件中飞书适配器通常需要以下配置# 飞书应用凭证 FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETyour_app_secret # 事件订阅回调路径 FEISHU_EVENT_ENDPOINT/feishu/event # 加密和解密用的 Encrypt Key FEISHU_ENCRYPT_KEYyour_encrypt_key # 验证用的 Verification Token FEISHU_VERIFICATION_TOKENyour_verification_token配置完成后需要到飞书开放平台后台填写“事件订阅”的回调地址。回调地址格式为http://你的公网域名或IP/feishu/event在飞书后台点击“订阅事件”添加机器人接收消息事件。保存时飞书会发送一个 URL 验证请求WorkBuddy 会返回加密串完成校验。验证通过后重启 WorkBuddy再向机器人发送一条“你好”如果返回正常飞书接入就完成了。4. 接入企业微信应用创建与主动消息4.1 企业微信自建应用创建流程接入企业微信的思路和飞书类似但后台入口和参数名称不同。企业微信里WorkBuddy 本质上是一个“自建应用”。创建步骤如下登录企业微信管理后台。进入“应用管理” “应用” “自建应用”。点击“创建应用”上传应用 Logo填写应用名称。创建完成后能看到 AgentId 和 Secret。配置“企业可信 IP”把 WorkBuddy 所在服务器的公网 IP 加入白名单。在“接收消息”中填写回调 URL用于接收用户的文本消息和服务端事件。另外企业微信里有一个全局参数 CorpID也就是企业 ID。在管理后台“我的企业”页面可以找到。企业微信接口调用需要三个关键参数CorpID企业唯一标识。AgentId自建应用的 Agent ID。Secret自建应用的密钥。4.2 获取企业微信 Webhook 并发送测试消息和飞书一样企业微信也有群机器人 Webhook适合快速验证消息通道。在某个企业微信群中点击右上角“群设置” “群机器人” “添加机器人”就可以生成一个 Webhook 地址。 文件路径examples/wecom_webhook.py 功能向企业微信群聊发送文本消息 用法python wecom_webhook.py import requests import json def send_wecom_webhook(webhook_url: str, content: str): 推送企业微信文本消息 :param webhook_url: 企业微信机器人 Webhook 地址 :param content: 发送的文本内容 headers { Content-Type: application/json } payload { msgtype: text, text: { content: content } } response requests.post(webhook_url, headersheaders, datajson.dumps(payload)) print(HTTP 状态码:, response.status_code) print(响应内容:, response.text) if __name__ __main__: url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyYOUR_KEY send_wecom_webhook(url, WorkBuddy 企业微信通道测试消息)如果群内收到消息说明企业微信的 Webhook 通道正常。4.3 通过 access_token 发送应用消息Webhook 只能发消息到配置了机器人的群而应用消息可以主动推送给指定用户适合做任务提醒、审批通知。调用企业微信 API需要先获取 access_token然后调用 message/send 接口。 文件路径examples/wecom_send_app_message.py 功能通过企业微信应用向指定用户发送文本消息 import requests def get_access_token(corp_id: str, corp_secret: str) - str: 获取企业微信 access_token url https://qyapi.weixin.qq.com/cgi-bin/gettoken params { corpid: corp_id, corpsecret: corp_secret } response requests.get(url, paramsparams) data response.json() if data.get(errcode) ! 0: raise RuntimeError(f获取 access_token 失败: {data}) return data[access_token] def send_text_message(access_token: str, agent_id: int, user_ids: str, content: str): 向指定用户发送应用消息 :param access_token: 企业微信 access_token :param agent_id: 自建应用 AgentId :param user_ids: 用户 UserID多个用 | 分隔 :param content: 文本内容 url https://qyapi.weixin.qq.com/cgi-bin/message/send params { access_token: access_token } payload { touser: user_ids, msgtype: text, agentid: agent_id, text: { content: content } } response requests.post(url, paramsparams, jsonpayload) data response.json() if data.get(errcode) ! 0: raise RuntimeError(f消息发送失败: {data}) print(消息发送成功:, data) if __name__ __main__: corp_id 你的企业ID corp_secret 你的应用Secret agent_id 1000002 token get_access_token(corp_id, corp_secret) send_text_message(token, agent_id, zhangsan, WorkBuddy 应用消息测试)这里的关键点是access_token 有效期是 7200 秒应该做缓存不要每次都请求。企业可信 IP 没有配置时接口会返回60020错误。UserID 不是手机号或姓名需要在企业微信通讯录里查看。4.4 在 WorkBuddy 中配置企业微信连接WorkBuddy 的企业微信适配器配置同样放在环境变量或配置文件中# 企业微信凭证 WECOM_CORP_IDyour_corp_id WECOM_AGENT_ID1000002 WECOM_SECRETyour_wecom_secret # 回调服务 WECOM_CALLBACK_URL/wecom/callback WECOM_TOKENyour_callback_token WECOM_ENCODING_AES_KEYyour_encoding_aes_key企业微信的回调机制比飞书更繁琐一些需要配置 Token 和 EncodingAESKey。保存回调 URL 后需要点击“保存”企业微信会向该地址发送一个验证请求。WorkBuddy 如果已经实现了适配器逻辑会自动完成签名校验和明文解密。整体流程完成后你可以在企业微信中给自建应用发一条消息正常情况下 WorkBuddy 会给出回复。5. 实战案例用飞书多维表格做任务管理5.1 案例需求与设计假设业务场景是这样的每天销售团队会把跟进客户的情况发到飞书群里我们希望 WorkBuddy 在飞书群里收到消息后自动把消息里的客户名称、跟进人、销售阶段写入一张多维表格。这个案例涉及三层能力飞书机器人接收群消息。解析自然语言文本。调用多维表格 API 写入数据。先准备好一张多维表格或者让 WorkBuddy 通过 API 自动创建。下面演示如何用 Python 调用飞书多维表格 API。5.2 创建多维表格调用飞书 API 前需要先获取 tenant_access_token它是应用级别访问凭证。 文件路径examples/feishu_tenant_token.py 功能获取飞书 tenant_access_token import requests import json def get_tenant_access_token(app_id: str, app_secret: str) - str: url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal headers { Content-Type: application/json } payload { app_id: app_id, app_secret: app_secret } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f获取 tenant_access_token 失败: {data}) return data[tenant_access_token]拿到 token 后创建表格。飞书多维表格的字段类型中1 表示文本3 表示单选。 文件路径examples/feishu_create_table.py 功能在多维表格中创建数据表 import requests import json def create_table(tenant_access_token: str, app_token: str, table_name: str): url fhttps://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables headers { Authorization: fBearer {tenant_access_token}, Content-Type: application/json } payload { table: { name: table_name, fields: [ { field_name: 客户名称, type: 1 }, { field_name: 跟进人, type: 1 }, { field_name: 销售阶段, type: 3, property: { options: [ {name: 初步沟通}, {name: 方案演示}, {name: 商务谈判}, {name: 已成交} ] } } ] } } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f创建数据表失败: {data}) print(数据表创建成功, data[data][table_id])其中app_token是多维表格应用的 token在飞书多维表格 URL 里可以看到。5.3 写入与更新记录创建完表之后就可以在收到群消息时调用写入接口。 文件路径examples/feishu_add_record.py 功能向多维表格数据表添加一条记录 import requests import json def add_record(tenant_access_token: str, app_token: str, table_id: str, customer: str, owner: str, stage: str): url fhttps://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records headers { Authorization: fBearer {tenant_access_token}, Content-Type: application/json } payload { fields: { 客户名称: customer, 跟进人: owner, 销售阶段: stage } } response requests.post(url, headersheaders, datajson.dumps(payload)) data response.json() if data.get(code) ! 0: raise RuntimeError(f写入记录失败: {data}) print(记录写入成功record_id:, data[data][record][record_id])这样一条客户跟进记录就自动进了多维表格。团队在飞书群里说的内容会沉淀成结构化数据后续可以再接入 BI 工具做统计。5.4 将表格操作封装成 WorkBuddy Skill上面的 Python 脚本可以直接用但在 WorkBuddy 中更推荐把这类操作封装成 Skill这样 Agent 才能自动决定何时调用。WorkBuddy 中一个 Skill 通常包含名称、描述、触发方式和可执行工具。下面用常见的 JSON 风格做一个示例具体字段以你使用的版本文档为准{ name: feishu_customer_tracking, description: 当用户提供客户名称、跟进人和销售阶段信息时写入飞书多维表格客户跟进表, trigger: { type: keyword, keywords: [客户, 跟进, 销售阶段] }, tools: [ { name: feishu.bitable.add_record, config: { app_token: your_app_token, table_id: your_table_id } } ] }之后在飞书群里发送“新增客户某某科技跟进人张三阶段方案演示”WorkBuddy 就会匹配到这个 Skill调用表格写入工具并回复“已记录”给群聊。6. 进阶模型接入与任务待办自动化6.1 在 WorkBuddy 中配置大模型WorkBuddy 的对话能力依赖底层大模型。目前国内外主流模型都有兼容方案可以通过配置模型供应商名和 API Key 接入。在配置文件中通常会有类似这样的配置MODEL_PROVIDERdeepseek MODEL_API_KEYyour_deepseek_api_key MODEL_NAMEdeepseek-chat MODEL_TEMPERATURE0.3接入 DeepSeek 时需要注意API Key 是敏感信息不要提交到 git 仓库。生产环境建议通过环境变量注入而不是写死在文件里。模型名称请以 DeepSeek 官方文档为准不同时期命名可能不同。6.2 企业微信任务待办示例在企业微信中把智能助手接入任务待办是很常见的需求。结合前文的应用消息 API我们可以做一个简单的“日报提醒”流程每天 18:00 触发定时任务。WorkBuddy 询问未提交日报的员工。员工把日报内容直接发给应用。WorkBuddy 调用消息发送接口回复确认信息。这个流程的关键代码如下import requests import json def send_template_card(access_token: str, agent_id: int, user_id: str, task_content: str): 向用户发送模板卡片消息 url https://qyapi.weixin.qq.com/cgi-bin/message/send params {access_token: access_token} payload { touser: user_id, msgtype: template_card, agentid: agent_id, template_card: { card_type: text_notice, source: { icon_url: , desc: WorkBuddy 日报提醒 }, main_title: { title: 今日待办提醒 }, horizontal_content_list: [ { keyname: 任务名称, value: task_content } ], card_action: { type: 1, url: https://example.com } } } response requests.post(url, paramsparams, jsonpayload) print(response.json())模板卡片比纯文本消息的展示效果更好适合待办、审批、通知类场景。6.3 待办自动化的建议任务待办自动化最容易出错的地方是“重复执行”和“错误处理”。建议在实现时考虑幂等性同一条待办被重复推送时不要产生重复记录。超时处理调用模型超时后要记录日志并进入重试队列。人工确认高风险的自动执行动作比如删除记录、发送外发消息应当设置人工确认环节。权限隔离不同部门的 Agent Skill 应有不同的数据访问范围。7. 常见问题与排查思路7.1 问题排查表格下面是我在搭建和运行过程中遇到的高频问题整理成表格方便快速定位问题现象常见原因解决思路飞书事件订阅验证失败回调地址无法访问或 Encrypt Key 配置错误确认服务器公网可达检查 Encrypt Key 和 Verification Token飞书机器人不回复群消息没有订阅 im.message.receive_v1 事件在飞书后台重新订阅事件并确认版本已发布上线企业微信应用消息报错 60020服务器 IP 未加入企业可信 IP在自建应用配置中添加入口服务器的公网 IP企业微信 access_token 获取失败CorpID 或 Secret 填写错误核对管理后台参数注意 Secret 中不可有空格发送消息报错 40058参数格式不正确检查 touser、msgtype、agentid 是否有缺失大模型接口超时网络不稳定或模型服务繁忙增加超时时间配置重试和熔断表格数据写入失败但接口返回 0App Token 或 Table ID 不对检查多维表格 URL 中的 app_token 和 table_id数据库锁相关报错并发写入压力大SQLite 不适合高并发生产环境切换 MySQL / PostgreSQL7.2 典型错误处理服务无法启动时第一步不是改代码而是看日志。WorkBuddy 一般会输出每个适配器的加载情况如果某个适配器配置缺失日志里会提示。排查顺序建议是检查环境变量是否加载完整。检查端口是否被占用。检查数据库连接是否可用。检查回调地址是否能从公网访问。检查对应平台后台的权限是否齐全。用最小复现方式调试比如先只用 Webhook 发一条消息。验证消息链路时可以先用最简单的 Webhook 脚本确认网络再逐个增加复杂度不要一上来就调试完整 Agent 流程。8. 最佳实践与工程建议8.1 权限与密钥管理密钥管理是这类项目最容易出安全问题的点。App Secret、API Key 都是敏感凭据不要提交到代码仓库。建议使用环境变量或者专业的密钥管理服务。在 .env.example 中使用占位符而不是真实值。给飞书和企业微信应用分配最小权限只申请必要的权限范围不要图省事全选。8.2 消息频率与限流飞书和企业微信对消息 API 都有频率限制。当系统告警集中爆发时如果直接调用 API 推送会触发限流导致消息丢失。一个合适的方案是在 WorkBuddy 和 IM 平台之间加入简单队列。消息先进入队列再按固定速率推送队列积压时通过日志告警。8.3 多环境配置本地开发、测试、生产环境应使用不同的配置和不同的自建应用。我推荐的配置方式.env.local # 本地开发可关闭 HTTPS 校验 .env.test # 测试环境使用测试企业 .env.production # 生产环境使用正式飞书/企业微信应用8.4 日志与监控生产环境必须做好日志和监控。保存 WorkBuddy 运行日志至少保留 7 天。监控消息成功率连续失败时发送告警。监控回调接口响应时间建议 P95 小于 1 秒。监控模型 API 调用成本。如果线上出现消息不回复的情况最有效的排查手段是看“一条消息从 IM 进入 WorkBuddy 后走了哪个 Skill最终是否被消费”所以日志里一定要打印 trace_id 或 request_id。9. 总结与下一步学习路线9.1 10 节课程的学习路径到这里你已经了解 WorkBuddy 的安装、飞书接入、企业微信接入、多维表格实战、任务待办和部分排错思路。如果你想系统学习建议按我整理的 10 节开源课程顺序推进快速上手先跑通本地 demo。读懂源码结构知道每个包管什么。完成飞书机器人配置体验消息收和发。完成企业微信应用配置体验主动推送。理解 Agent 处理消息的完整链路。从现成 Skill 开始改再写自己的 Skill。用多维表格做数据沉淀。实现一个带状态的任务待办。接入 DeepSeek 或其他模型体验不同模型的效果差异。部署到公网服务器配置日志、监控和守护进程。每一步都可以在我整理的开源文档中找到对应的代码和配置示例。文档中缺失的细节建议结合平台官方 API 文档再核对因为飞书和企业微信的接口处于快速迭代期版本差异较大。9.2 继续精进的方向当你跑通基础流程后还可以继续扩展这些方向把 WorkBuddy 与内部接口对接当成统一 API 助手。结合 MCP 协议让 WorkBuddy 调用更多外部工具。加入定时触发能力做日报、周报自动生成。接入更多办公平台让一套 Agent 引擎服务多个业务系统。最后给你一个实用建议先从一个最小业务场景开始例如“把飞书群消息写入多维表格”跑通后再逐步叠加功能。不要把第一版设计得太复杂否则排错时会很难定位问题。如果这篇文章对你有帮助建议收藏备用动手实现时绝大多数步骤都能直接对照操作。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
