夜雨聆风
· · ·
大家好，我是及时雨。
上周三下午三点，产品经理在飞书群里 @ 我："明早九点要给客户演示，能不能赶一份 PPT 出来？"
我没回他。我只在群里 @ 了一个机器人，打了一行字："帮我写一份产品演示 PPT，主题是 DeerFlow 2.0 的 Harness 架构，15 页左右，商务风。"
八分钟后，机器人在群里甩出了一份 .pptx。产品经理看完只回了三个字："牛逼啊。"
这个机器人，就是字节刚开源的 DeerFlow 2.0 接进飞书群之后的样子——不是 Demo，不是玩具。是一个真的可以让全公司的人在群里直接喊话、自动执行任务、产出文件的 AI 工作台。
这篇文章会把整个接入过程、踩过的坑、以及为什么飞书是 DeerFlow 最适合的"前脸"全部讲清楚。读完你应该能在两个小时内，让自己的团队也用上。
· · ·
聊 Agent 落地，绕不开一个老问题。
入口在哪里？
过去两年我见过太多团队，吭哧吭哧做了一个 Agent，最后给它套一个 React 写的对话框界面，发到内网让大家用。
第一周有人尝鲜。第二周流量减半。第三周这个网址就没人记得了。
问题不是 Agent 不好用。是入口错了——员工日常的工作不在那个网页里，他们在飞书里。
IM 是 Agent 最天然的入口。三点原因。
第一，工作上下文已经在那里。同事的对话、文件、日程都沉淀在 IM 里。Agent 进群就等于带着上下文上岗。
第二，协作天然存在。你给同事派活的方式和给机器人派活，可以完全一致。零学习成本。
第三，异步化。产品经理在飞书喊一句，下班前 PPT 自然就在群里了。不需要谁守着浏览器等结果。
DeerFlow 2.0 的 Channels 系统内置了 5 个 IM 适配器——飞书、微信、钉钉、Slack、Telegram。其中飞书是支持最完整的一个。
下面进入实战。
· · ·
整个流程没有想象中复杂。核心就三步：创建应用 → 拿到密钥 → 告诉 DeerFlow 怎么连。
第 1 步：创建飞书自建应用
打开飞书开放平台[1]，登录后进入"开发者后台"，点击"创建企业自建应用"。
填两件事就够了：应用名称（比如 "DeerFlow Bot"）、应用图标。提交后你会拿到一个应用主页。
记住左侧菜单里的两个关键项："凭证与基础信息"里的 App ID 和 App Secret，以及"事件与回调"——待会儿回来配。
第 2 步：开启机器人能力，拿到密钥
在应用主页左侧菜单里找"添加应用能力"，把"机器人"那一项启用。
然后回到"凭证与基础信息"，把 App ID 和 App Secret 抄下来。这两个值就是飞书识别你这个机器人的身份证号和密码：
App ID: cli_a1b2c3d4e5f6App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx第 3 步：配置事件回调 URL
事件回调，就是"群里有人 @ 你机器人时，飞书把消息发到哪里"。
在飞书后台的"事件与回调 → 事件配置"里，填写你的服务地址：
https://your-domain.com/api/v1/channels/feishu/event这个路径是 DeerFlow 2.0 在 channels/feishu/event/handler.py 里默认暴露出来的。
如果你本地开发，强烈建议用 ngrok 或者飞书自带的 cli 工具做一个公网穿透。否则飞书的回调到不了你的开发机。
然后在"事件订阅"里加一个事件：接收消息 v2.0（im.message.receive_v1）。
第 4 步：修改 channels/feishu 的配置
回到 DeerFlow 项目，进到 channels/feishu/config/ 目录。打开 feishu.yaml：
feishu: app_id: "cli_a1b2c3d4e5f6" app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" verification_token: "VxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX" encrypt_key: "" event_callback_path: "/api/v1/channels/feishu/event" enable_card_message: trueverification_token 在飞书后台"事件与回调 → 加密策略"里能找到。
encrypt_key 如果你没开消息加密就留空。强烈建议第一次接入时不要开加密，等跑通了再加。
第 5 步：docker compose 起服务
DeerFlow 2.0 的 docker compose 已经把 Gateway、Harness、Channels 都编排好了：
cd deerflowcp .env.example .env# 把刚才的 App ID/Secret 写进 .env 里docker compose up -d起来之后，看一下 Channels 服务的日志：
docker compose logs -f channels如果你看到这一行：
[feishu] event handler registered at /api/v1/channels/feishu/event[feishu] bot online: cli_a1b2c3d4e5f6恭喜，机器人已经活了。
把机器人拉进任何一个飞书群，@ 它一句"你好"，应该秒回。如果没有回应——往下看踩坑点。
· · ·
写 PPT 只是最浅的一个用法。我在自己的团队里跑了两周，沉淀出三个真实在用的场景。
场景一：群里直接查生产数据库。
产品经理："@DeerFlow 上周下单转化率比前周高还是低？"
DeerFlow 调用了 Skills 里的 sql_query，连到只读副本，跑完查询、生成图表、发回群里。
整个过程产品经理不需要懂 SQL、不需要打开 BI、不需要 ping 数据团队。
场景二：自动整理会议纪要 + 派活。
复制一段飞书会议的转写文字丢给 DeerFlow："@DeerFlow 这是刚才的会议纪要，把待办拆成飞书任务，按人分配。"
它会调用飞书任务 API，把每个 action item 创建成对应同事的任务卡片，自动 @ 当事人。
场景三：跨系统协调日程。
"@DeerFlow 帮我和张三、李四下周找一个 1 小时的空档开会，会议室订璞玉。"
DeerFlow 通过飞书日历 API 查三个人的空闲时间、查会议室占用、发出会议邀请。全过程在群里完成，没有任何切窗口。
这三个场景有一个共同点：用户根本没意识到自己在用一个 Agent。他们以为只是在群里 @ 了一个同事。
这才是 IM 入口的杀手级价值。
· · ·
第一个坑我卡了半小时。第二个卡了将近三小时。你提前看过这篇，应该十分钟就能绕过。
坑一：channel_id 不是群 ID，是 chat_id
DeerFlow 的 channel 配置里有一个 channel_id 字段。新手很容易直接把飞书群的 URL 里那串数字粘进去——这是错的。
飞书的"群 ID"在 API 体系里有三套：群 URL 里的数字、open_chat_id、chat_id。你需要的是 chat_id，格式形如 oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。
最稳妥的拿法：让机器人进群之后，在 DeerFlow 的日志里直接看。每次群里有消息进来，handler 都会打印当前 chat_id：
[feishu] received message from chat_id=oc_abc123def456..., user_id=ou_xxx, text="@DeerFlow 你好"把这个 oc_ 开头的字符串复制进配置就对了。
坑二：签名校验的 sha1 vs sha256 血泪
这个坑我个人卡了快 3 个小时。
飞书的事件回调签名校验，老版本用 sha1，新版本用 sha256。如果你最近半年内创建的应用，飞书会默认走 sha256。但 DeerFlow 早期代码里的 verify_signature 函数还有些路径在用 sha1。
如果你看到日志里反复刷：
[feishu] signature verification failed, expected=xxxxx, got=yyyyy但你又确定 token 没填错——99% 是这个坑。
解法：打开 channels/feishu/security/signature.py，确认计算签名的代码是这样的：
import hashlibdef verify_signature(timestamp: str, nonce: str, encrypt_key: str, body: bytes) -> str: content = (timestamp + nonce + encrypt_key).encode("utf-8") + body return hashlib.sha256(content).hexdigest()如果这里还是 hashlib.sha1，改成 sha256 即可。
这个 PR 在 DeerFlow 主仓里已经合并了。但如果你 fork 的是几个月前的版本，记得手动改一下。
· · ·
DeerFlow 的 Channels 一共支持 5 个 IM——飞书、微信、钉钉、Slack、Telegram。我五个都跑过。
最终选飞书做主入口，原因不在"用的人多"。在三个独有工程优势。
第一，消息卡片是真的可交互的。
飞书的 Interactive Card 支持按钮、下拉、多选、表单。DeerFlow 可以让用户点"批准/驳回/修改"按钮触发后续 Agent 流程。
Slack 的 Block Kit 类似但学习曲线陡。钉钉的卡片偏静态。微信企业号几乎没有可交互卡片。Telegram 的 inline keyboard 太简陋。
消息卡片决定了 Agent 是"对话玩具"还是"真生产工具"。
第二，审批流原生集成。
飞书的审批 API 让 DeerFlow 可以做"AI 起草 → 人审批 → 自动执行"的闭环。
比如机器人写完 PPT 后，自动发一个审批给老板看。老板点通过才发到客户群。
这套流程在其他 IM 里要么没有，要么是第三方插件凑合的。
第三，云文档是 Agent 的天然产物落地点。
DeerFlow 写完的文档、表格、PPT 可以直接落到飞书云文档里。权限继承、版本管理、协同编辑全部开箱即用。
Slack 没有原生云文档——要跳转 Notion/Google Docs。微信压根没有。Telegram 是个发文件的渠道而已。
一句话总结：其他 IM 把 Agent 当成"聊天机器人"，飞书把 Agent 当成"虚拟员工"。
后者才是 DeerFlow 这种 Harness 真正的形态。
· · ·
🤨 机器人不需要"管理员权限"也能干很多活。 我一开始以为得给机器人开各种权限才能查数据、建文档。实际上飞书的"被动响应"机制很灵活——用户 @ 它的时候，机器人能借用调用者的身份令牌做事，权限完全跟着人走，省了一大堆 OAuth 坑。
😐 群越多，DeerFlow 越省钱。 反直觉的点在于：每个群是一个独立的 session，但 Memory 是按 user 隔离的。一个用户在 5 个群里跟机器人聊，背后是同一份记忆。上下文复用，token 消耗不会线性增长，反而降低了。
🤔 回复速度的瓶颈不在模型，在飞书 API。 跑下来真正的延迟大头是飞书的"上传文件"接口——PPT 这种几百 KB 的文件要 2-3 秒。模型推理加 Agent 编排只占总耗时的 30%。
如果你要优化用户感知，先做"先发文字预览，文件后补"。比换更快的模型有效得多。
· · ·
把 Agent 接到飞书只是 DeerFlow 落地的第一步。
更值得聊的问题是：它和 LangGraph、CrewAI、AutoGen 到底是什么关系？
下一篇会用 14 个维度做一次彻底对比，把"Framework 还是 Harness"这件事讲到位。
· · ·
我是及时雨，我们下篇见。
参考链接:
[1] https://open.feishu.cn/
