飞书里也能指挥电脑干活：WorkBuddy 接入完整流程
本篇涵盖的知识重点
- 需要一个有创建应用权限的飞书企业账号，且已开启助理远程控制
- 在飞书开放平台点击「创建企业自建应用」并填写名称、描述、图标
- 在「添加应用能力」区域找到「机器人」卡片并点击「添加」
- 通过「权限管理 → 批量导入 / 导出权限」导入 tenant 与 user 两组 scopes
- 凭证包含 App ID、App Secret，以及 Encrypt Key 与 Verification Token
- 必须添加「接收消息」事件并配置「卡片回传交互」回调，且应用需发布后才能使用
配置流程导览
配置步骤详解
作用没有创建应用权限就连第一步都走不下去，先确认能省很多来回。
操作确认已在电脑上安装 WorkBuddy 并开启了助理远程控制功能；准备一个拥有创建应用权限的飞书企业账号。
注意个人版账号通常不具备创建企业自建应用的权限，请以实际账号能力为准。
作用飞书机器人必须挂在某个应用下，先把应用建出来才有后续配置。
操作打开浏览器访问飞书开放平台，使用企业账号登录后点击「创建企业自建应用」；在创建窗口中填写应用名称、应用描述，并上传应用图标；点击「创建」按钮。
注意创建成功后会自动跳转到应用详情页面，后续配置都在这个页面完成。
- 应用名称：给应用起一个名字，如「WorkBuddy 助手」，后续在飞书搜索框里靠它找到机器人。
- 应用描述：简单描述应用的功能，会出现在应用详情里，方便同事识别。
- 应用图标：上传一个应用图标，建议与团队视觉统一，便于在通讯录里辨认。
- 填写完成后点击「创建」，系统会自动跳转到应用详情页。
作用没有机器人能力和对应权限，应用既收不到消息也发不出去。
操作在应用详情页的「添加应用能力」区域，找到「机器人」卡片点击「添加」；再进入左侧菜单「权限管理」，选择「批量导入 / 导出权限」；在弹出的窗口中清空输入框原有内容，把官方文档给出的权限列表完整复制粘贴进去，点击「确定新增权限」。
注意务必先清空输入框原有内容再粘贴，否则可能与原有权限冲突；等待几秒钟，页面会提示权限已成功添加。
- 权限分两组：官方文档给出的是一段 JSON，包含 tenant 与 user 两组 scopes，必须完整复制，不能只取一半。
- tenant 组：覆盖通讯录、消息发送与撤回、群会话、卡片、应用自管理等企业级权限。
- user 组：覆盖多维表格、日历、云文档、云空间、任务、知识库等用户级权限。
- 导入动作：清空输入框全部内容 → 完整粘贴权限列表 → 点击「确定新增权限」→ 等待几秒提示添加成功。
作用WorkBuddy 要靠这些凭证与飞书通信，少一个都注册不上。
操作在应用详情页左侧菜单点击「凭证与基础信息」，获取 App ID 与 App Secret（密钥需点击查看）；再点击左侧「事件与回调」，在右侧页面中选择加密策略，点击刷新按钮自动生成，或点击编辑按钮自定义 Encrypt Key 和 Verification Token。
注意App Secret、Encrypt Key 和 Verification Token 都要妥善保管，不要泄露给他人。
作用这一步决定 WorkBuddy 用哪种方式和飞书保持通信，选错会导致收不到消息。
操作在 WorkBuddy 中点击助理的设置图标进入助理设置，找到飞书集成开始配置；将 App ID、App Secret 以及 Encrypt Key 填入对应输入框，选好模式后点击「注册」。
注意长连接模式点击「注册」后配置成功会显示已连接；URL 回调模式点击「注册」后系统会生成 Webhook 地址，需点击复制保存。
- WebSocket 长连接模式：适用于个人 / 家庭 / 办公室用户（没有公网 IP），配置更简单，不需要公网地址，开箱即用。
- 使用 URL 回调模式：适用于有服务器、有公网 IP 的用户，需要额外在飞书开放平台填写生成的 Webhook 地址。
- 选型建议：没有公网 IP 一律选长连接；已有服务器且需要回调地址时再选 URL 回调。
作用事件订阅决定飞书把消息发到哪里，缺了「接收消息」事件机器人根本收不到内容。
操作返回飞书开放平台进入应用详情页，左侧点击「事件与回调」。长连接模式在「订阅方式」中选择「使用长连接接收事件」并点击「验证」，成功显示「连接成功」；URL 回调模式选择「将事件发送至开发者服务器」，粘贴 Webhook 地址并点击「保存」。随后在「事件配置」区域点击「添加事件」，搜索并添加「接收消息」事件。
注意订阅方式与 WorkBuddy 侧选择的模式必须一致，一边长连接一边 URL 回调会直接收不到消息。
作用应用必须发布后才能在飞书中使用，卡片回调缺失则交互式消息无法回传。
操作在「事件与回调」中切换到「回调配置」页签，搜索「卡片回传交互」并点击「确认添加」；随后点击页面上方「创建版本」，填写版本号与版本描述，点击「确定」，再点击版本右侧的「发布」。
注意如果您是企业管理员，应用通常会自动审批通过；如果需要审批，请联系您的企业管理员。
- 版本号：示例为 1.0.0，按语义化版本填写即可。
- 版本描述：示例为「首次发布，集成 WorkBuddy」，简短说明本次发布内容。
- 发布动作：点击「确定」创建版本，再点击版本右侧的「发布」按钮完成上线。
作用发布只是能用了，真正跑通一次才算接入完成。
操作在飞书的搜索框中输入刚才创建的机器人名称进行搜索；点击机器人进入对话窗口，或点击「打开应用」开始使用；直接发送你的需求，比如「帮我写一个待办事项应用」。WorkBuddy 会在电脑上自动执行任务，并将结果返回给你。
注意机器人无响应时，依次检查应用是否已成功发布、电脑上的 WorkBuddy 是否运行且助理服务已开启、Webhook 地址是否正确、权限是否已全部导入。
常见故障排查
- App Secret 请务必妥善保管，不要泄露给他人。
- Encrypt Key 和 Verification Token 同样务必妥善保管，不要泄露给他人；可在「事件与回调」中用刷新按钮自动生成，或用编辑按钮自定义。
- 权限导入前必须清空输入框中的所有内容，再粘贴官方给出的完整权限列表。
- 应用必须发布后才能在飞书中使用；如果您是企业管理员，应用通常会自动审批通过，如需审批请联系企业管理员。
- 机器人没有响应：检查应用是否已成功发布；确保电脑上的 WorkBuddy 正在运行且助理服务已开启；确认 Webhook 地址配置正确；检查所有权限是否都已正确导入。
- 收不到消息：确认已添加「接收消息」事件、已配置「卡片回传交互」回调，并检查事件订阅中的 Webhook 地址是否正确。
练手任务
```markdown
我要在飞书开放平台创建一个用于连接 WorkBuddy 的企业自建应用。请帮我整理一份配置清单，表格列包含：配置项、填写内容建议、在哪里填、注意事项。至少要覆盖应用名称、应用描述、应用图标、机器人能力、权限导入这五项。
```得到一张含填写建议与注意事项的配置清单，可按表逐项完成飞书应用创建。
```markdown
在把飞书接入 WorkBuddy 时，需要在「使用长连接接收事件」和「将事件发送至开发者服务器」之间二选一。请帮我做一份对比说明：分别写出两种方式的适用人群、是否需要公网 IP 或公网地址、配置步骤的多少、WorkBuddy 侧需要填写什么。最后给我一句「什么情况下选哪种」的判断建议。
```得到一份清晰的对比说明与选型建议，能据此判断自己该走哪条路。
```markdown
我完成了飞书机器人的接入，但给它发消息没有收到回复。请给我一份排查清单，表格列包含：检查项、具体看哪里、异常时怎么处理。至少 5 行，必须覆盖「应用是否已发布」「电脑上的 WorkBuddy 是否运行且助理服务已开启」「Webhook 地址是否正确」「权限是否全部导入」「是否添加了接收消息事件和卡片回传交互回调」这几项。
```得到一张不少于 5 行的排查表，覆盖发布状态、运行状态、地址、权限与事件配置。
```markdown
请帮我写一份《WorkBuddy 接入飞书操作手册》，供团队内部使用。结构要求：前提条件、创建应用、添加机器人能力、配置权限、获取凭证、WorkBuddy 侧配置、配置事件回调、发布应用、开始使用、常见问题。每节用编号步骤写，步骤里的按钮名和菜单路径必须写准确。篇幅控制在 1200 字以内。
```得到一份结构完整、按钮与菜单路径准确、篇幅在 1200 字以内的内部操作手册。
本文基于官方文档再创作，具体以官方文档站实际展示为准。