从零开始搭建飞书智能助手——前期准备

前置准备

1. 拥有企业飞书账号（个人版无法创建自建机器人应用），且你是企业管理员 / 有应用创建权限
2. 浏览器打开飞书开放平台官网：https://open.feishu.cn
3. 本地 Java 项目默认端口：8080（SpringBoot 默认），后续内网穿透映射 8080 端口
4. 工具：ngrok（内网穿透，开发阶段必须，飞书云端无法直接访问本地[localhost]）

第 1 步：登录开发者后台，创建企业自建应用

飞书开放平台首页

1. 点击右上角登录，用电脑飞书扫码登录
2. 进入右上角「开发者后台」
3. 首页点击创建企业自建应用
4. 填写应用信息（自用随意填）
   • 应用名称：个人 AI 智能管家
   • 应用描述：飞书驱动 Java 个人台账 + AI 知识库机器人
   • 应用图标：自选 / 跳过
5. 点击创建，进入应用详情页

第 2 步：保存核心凭证 AppID & AppSecret（Java 对接必备）

左侧菜单：凭证与基础信息

1. App ID：cli_xxxxxxx（复制保存，Java 配置文件必填）
2. App Secret：点击「查看」复制，务必妥善保管，不要泄露
3. 记录「事件加密密钥」（后续回调解密用，可先复制）

第 3 步：开通机器人基础能力（必须）

左侧菜单：添加应用能力

1. 在能力列表找到机器人，点击「开通」
2. 开通后，应用获得收发飞书消息的基础身份

第 4 步：开通消息核心权限（收消息、发消息、读取文件）

左侧菜单：权限管理 → API 权限

搜索框依次输入下面权限，逐个开通：

1. im:message读取用户消息基础权限
2. im:message:send_as_bot机器人发送消息（回复卡片 / 文本）
3. im:message.p2p_msg:readonly读取私聊消息
4. im:resource下载飞书上传的文件（日志、PDF、图片）
5. contact:contact:readonly获取发送消息的你的用户信息

开通操作：选中权限 → 点击「开通权限」→ 确认开通，全部显示已开通

第 5 步：配置事件订阅（飞书消息推送到你的 Java 服务）

订阅方式选：将事件发送至开发者服务器

1. 请求地址填写：https://公网ip:host/feishu/event（/feishu/event 是 Java 写的回调接口路径
2. 保存，飞书会自动发送 challenge 校验请求，Java 接口需原样返回 challenge 才算校验成功

第 6 步：创建应用版本并发布（权限、事件才会生效！90% 人踩坑）

1. 开通权限、添加事件后不发布 = 不生效
2. 左侧菜单：应用发布 → 版本管理与发布
3. 右上角点击 创建版本
4. 版本号填：1.0.0，更新说明：初始化机器人基础能力
5. 全部下拉默认勾选，保存版本
6. 点击 申请发布，企业管理员通过审核（自己是管理员直接通过）

第 7 步：把机器人添加到飞书，私聊测试

1. 发布成功后，左侧菜单「机器人」，复制机器人对话链接
2. 电脑飞书浏览器打开链接，发起私聊
3. 发送消息测试：测试学习记录 Python 2小时
4. 此时 Java 服务启动后，就能收到这条消息事件

补充拓展配置（后续开发用到）

1. 文件上传能力（上传日志 / 图片 / PDF 给 AI 处理）
   事件与回调 → 添加事件：im.resource.upload_v1（文件上传事件），同步开通 im:resource 权限
2. 飞书表单回调（后续替代文字指令录入台账）
   添加事件：approval.instance.created_v1（表单提交事件），开通审批相关权限
3. 安全加密配置（HTTP 回调模式必开）
   事件与回调 → 加密策略，复制加密密钥到 Java 配置，用于解密飞书推送的加密消息