〇、先搞懂几个词（小白必读）
-
工作流：你在画布里搭的那套自动流程（如「收到文字 → AI 处理 → 回结果」）。
-
企业自建应用 / 机器人：你在飞书开放平台创建的一个应用，它带一个机器人，能自动收发消息。不是你的私人飞书账号。
-
Webhook（请求地址）：一个网址。用户给机器人发消息时，飞书把消息推送到这个网址（即推给我们的服务器），从而触发你的工作流。你要做的是把我们生成的网址填回飞书后台。
-
App ID / App Secret：应用的「身份 + 密钥」。App ID 是身份，App Secret 是密钥（换调用凭证、验签、发消息）。App Secret 保密。
-
Encrypt Key：加密密钥。开启后飞书推给我们的消息是加密的，能防别人伪造消息触发你工作流。强烈建议开。
-
权限 / 发版：机器人能做什么（读消息、发消息…）由「权限」决定；改完权限必须「发布版本」才生效——这是飞书最容易漏的一步。
一、你将得到什么
接好之后：
-
在飞书里给机器人发一句话或一张图，它就会触发你的工作流自动运行。
-
工作流跑完，结果（文字 / 图片）自动回到飞书，并引用你的原消息。
-
处理过程中，你的消息上会出现 ⏳ 处理中 表情，完成变 ✅、失败变 ❌。
-
失败时会收到一张失败卡片，点「诊断原因」按钮，AI 会逐字打出失败原因和修复建议。
二、开始前的准备
-
一个飞书企业自建应用（在 飞书开放平台 创建，选「企业自建应用」）。
-
一个已经搭好、且全部是后台节点的工作流。工作流的开始节点必须是「Webhook 开始」节点（不是普通的「开始」节点）。工作流里不能有需要在浏览器里操作的节点（如「文本输入」「文件上传」这类），因为飞书触发时没有浏览器。用「Webhook 开始」节点来接收飞书的文字和图片即可。
三、第一步：在飞书后台拿到 4 个凭据
进入你的应用 →「开发配置」→「凭证与基础信息」，记下这几个值（后面要填到工作流里）：
| 凭据 | 在哪找 | 是否必填 |
|---|---|---|
| App ID | 凭证与基础信息页 | 必填 |
| App Secret | 凭证与基础信息页 | 必填 |
| Verification Token | 「事件订阅」页 | 可填（系统目前不强制校验它） |
| Encrypt Key | 「事件订阅」页（开启加密推送后出现） | 强烈建议填 |
关于 Encrypt Key：它用于加密飞书推给我们的事件，并校验来源真实性。强烈建议开启并填写——这是防止别人伪造消息触发你工作流的关键。
界面位置：登录飞书开放平台 → 打开你的应用 → 左侧「开发配置 → 凭证与基础信息」。App ID、App Secret 就在这一页顶部并排显示，各自右侧有复制按钮；App Secret 可能需要点一下才完整显示。
四、第二步：开通机器人权限
进入应用 →「开发配置」→「权限管理」，开通以下权限。开完必须发版才生效（见第六步）。
必须开通（基础收发消息）
| 权限名称 | 权限标识 | 作用 |
|---|---|---|
| 读取用户发给机器人的单聊消息 | im:message | 接收你发给机器人的消息 |
| 以应用的身份发消息 | im:message:send_as_bot | 把工作流结果发回给你 |
| 获取与上传图片或文件资源 | im:resource | 下载你发的图、上传结果图/文件 |
可选开通（增强体验，不开也能用基础功能）
| 权限名称 | 权限标识 | 对应功能 |
|---|---|---|
| 创建、更新、删除应用消息流卡片 | im:app_feed_card:write | 「消息流进度提醒」开关：在消息列表顶部置顶一张进度条 |
| 调用即时提醒能力 | im:datasync.feed_card.time_sensitive:write | 上面那张进度条「常驻置顶」 |
| 创建与更新卡片 | cardkit:card:write | 失败诊断的「逐字打字机」效果 |
不开可选权限也能正常用——只是少了进度置顶条和打字机诊断这些锦上添花的体验。
界面位置：应用内「开发配置 → 权限管理」，页面有一个权限搜索框。逐个搜索
im:message、im:message:send_as_bot、im:resource三个权限标识，在搜索结果里点右侧「开通」。开通后权限会出现在「已开通权限」列表里——注意此时还没生效，必须完成第六步发版。
五、第三步：在工作流画布里填凭据 + 拿到 Webhook 地址
-
打开你的工作流画布，点中「Webhook 开始」节点。
-
在右侧配置里：触发平台：选「飞书」。飞书 App ID / App Secret / Encrypt Key：填第一步记下的值。交互模式：「自动」= 收到消息直接跑完（推荐，最省事）。「精细」= 重要节点执行前先弹卡片让你确认参数（适合生图这类要核对参数的场景）。消息流进度提醒（可选开关）：想要消息列表顶部置顶进度条就打开（需开通上面的可选权限）。
-
保存工作流。保存后这个工作流会有一个 ID（一长串 uuid，形如
0aeda01a-0f09-46e5-...）。 -
你的 Webhook 地址就是：
https://api.openai.run/v1/workflow/webhook/feishu/你的工作流ID
把末尾的「你的工作流ID」换成上一步的真实 ID。这个地址下一步要填回飞书。
六、第四步：在飞书后台配置事件订阅
进入应用 →「开发配置」→「事件与回调」：
-
配置请求地址（订阅方式选「将事件发送至开发者服务器」）：把第三步的 Webhook 地址填进「请求地址」。如果填了 Encrypt Key，这里的「加密策略 Encrypt Key」要填同一个值。保存时飞书会立即发一个验证请求，显示「验证通过」即成功。（Verification Token 这里会显示，记下填回工作流即可；系统当前不强制用它。）
-
添加事件：点「添加事件」，搜索并添加：接收消息（
im.message.receive_v1）—— 这是核心，没有它机器人收不到消息。 -
添加回调（用了「精细模式」或想要失败诊断按钮时必须加）：在「回调配置」里，请求地址填同一个 Webhook 地址。订阅回调：卡片回传交互（
card.action.trigger）—— 用于「确认/取消」「诊断原因」这些按钮的点击。
界面位置：应用内「开发配置 → 事件与回调」。上半部分「事件配置」里先填「请求地址」（你的 Webhook 地址），若用了加密再填「加密策略 Encrypt Key」，然后点「添加事件」搜索并勾选
im.message.receive_v1；下半部分「回调配置」单独填一次同一个请求地址，再在回调列表里勾选card.action.trigger。事件和回调是两块独立配置，都要填地址。
七、第五步：发版
权限和事件配置改完后，进入「应用发布」→「版本管理与发布」→ 创建版本并发布。
重要：飞书的权限和事件订阅必须发布版本才生效。只保存不发版，机器人还是收不到消息、没有权限。
八、第六步：把机器人拉进会话
-
群聊：把机器人添加到一个群里，在群里 @机器人 发消息。
-
单聊：在「应用功能 → 机器人」里开启机器人能力，然后直接私聊它。
九、第七步：在画布里启用工作流
回到工作流画布：
-
把触发方式设为 webhook。
-
启用该工作流。
只有「已启用 + webhook 触发」的工作流才会被飞书消息触发。如果忘了启用，机器人会回你一句「该工作流尚未启用 webhook 触发」。
十、测试
在飞书里给机器人发一句话（比如你工作流期望的输入）。正常情况下：
-
你的消息上很快出现 ⏳ 表情（处理中）。
-
几秒到几十秒后，机器人引用你的消息回复结果。
-
你的消息上的表情变成 ✅（成功）或 ❌（失败）。
-
如果失败，会多一张失败卡片，点「诊断原因」看 AI 分析。
十一、常见问题
Q：保存事件订阅地址时验证不通过？
-
检查 Webhook 地址末尾的工作流 ID 是否填对、工作流是否已保存。
-
如果填了 Encrypt Key，确认飞书后台「加密策略」里填的是完全相同的值。
Q：机器人收不到消息 / 没反应？
-
99% 是没发版。改完权限和事件后一定要发布版本。
-
确认已添加
接收消息事件、机器人已在群里或已开启单聊。 -
确认工作流已「启用 + webhook 触发」。
Q：发图片给它，它报错或没正确处理？
- 取决于你的工作流有没有处理图片的节点。如果工作流只接了文字处理（如纯对话），发纯图片可能因为没有文字输入而失败。请确认工作流的节点能消费图片输入。
Q：「精细模式」的确认卡片点了没反应？
- 确认在「事件与回调 → 回调配置」里订阅了
card.action.trigger回调，且回调地址填的是同一个 Webhook 地址，并已发版。
Q：换了机器人凭据后不生效？
- 在画布里更新「Webhook 开始」节点的凭据并重新保存工作流即可，无需改飞书后台（除非也换了应用）。
十二、权限速查表（一页纸）
必开（基础收发）：
im:message 读消息
im:message:send_as_bot 发消息
im:resource 收发图片/文件
选开（增强体验）：
im:app_feed_card:write 消息列表置顶进度条
im:datasync.feed_card.time_sensitive:write 进度条常驻置顶
cardkit:card:write 失败诊断打字机效果
事件订阅：
im.message.receive_v1 接收消息（必加）
回调订阅：
card.action.trigger 卡片按钮点击（精细模式/诊断按钮需加）
Webhook 地址：
https://api.openai.run/v1/workflow/webhook/feishu/<工作流ID>
改完权限/事件务必「发版」；改完工作流凭据务必「保存」并「启用」。