飞书接入新手指南（为什么需要 & 如何获取 5 个核心值）

0. 为什么需要飞书？要填哪几个值？实现什么功能？

┌──────────────────────────┐
│ 飞书开放平台（你的自建应用）│ ◄──── 凭证: App ID + App Secret (你的系统身份证)
│  ├─ 机器人能力 (收发消息) │
│  ├─ bitable 读写权限     │ ◄──── 授权: 多维表格加为「可编辑」协作者
│  └─ 事件订阅 (长连接模式) │
└────────┬─────────────────┘
         │ WebSocket 长连接 (无需公网 IP，双向通信)
         ▼
┌──────────────────────────┐
│ JobHunter 客户端 / 后端  │ ────► 岗位评估写入 ──► 岗位总表 (FEISHU_TABLE_ID_JOBS)
│  ├─ 战报与提醒推送       │ ────► 读取简历原文 ──► 简历库 (FEISHU_TABLE_ID_RESUMES)
│  └─ 接收群内 @机器人 指令 │ ────► 目标多维文档 ──► 文档 Token (FEISHU_APP_TOKEN)
└──────────────────────────┘

系统全量飞书配置项对账表（5 个核心必填 + 4 个进阶选填）

1. 第一幕：在开放平台建立专属系统身份（拿 App ID & Secret）

1. 打开 飞书开放平台 open.feishu.cn → 点击右上角「开发者后台」。
2. 点击「创建企业自建应用」，名称随意填写（如 求职助手），图标随意。
3. 创建完成后进入应用控制台：点击左侧「凭证与基础信息」→ 复制 App ID（cli_ 开头）和 App Secret，妥善存好。
4. 开启机器人能力：点击左侧「添加应用能力」→ 勾选「机器人」→ 点击保存。
5. 开通必要读写权限：点击左侧开发配置的「权限管理」→ 点击「开通权限」→ 确保选中顶部的「应用身份权限 (tenant_access_token)」（全系统后台自动运行，切勿选用户身份权限），搜索并勾选以下 3 个核心大权限：
   • 搜索 im:message：勾选「获取与发送单聊、群组消息」（im:message）。（顶级全能权限，已包含发消息、回复卡片、传图片附件）
   • 搜索 im:chat：勾选「获取与更新群组信息」（im:chat）或「获取群信息」im:chat:readonly。（用于客户端自检拉取群列表与下拉选择战报推送群，无需勾选建群、解散群等）
   • 搜索 bitable：勾选「查看、评论、编辑和管理多维表格」（bitable:app）。
6. 配置长连接事件与回调（免公网 IP 核心！）：点击左侧开发配置的「事件与回调」：
   • 事件配置（接收消息与群指令）：在「事件配置」标签页，将订阅方式改为「使用长连接接收事件」；点击右上角「添加事件」→ 搜索勾选「接收消息 v2.0」（im.message.receive_v1）。
   • 回调配置（响应战报卡片按钮交互）：切换至「回调配置」标签页，将订阅方式改为「使用长连接接收回调」；点击右上角「添加回调」→ 搜索勾选「卡片回传交互」（card.action.trigger）。
7. 创建并发布版本（全网生效关键！）：点击左侧应用发布的「版本管理与发布」→ 点击「创建版本」并提交发布（通常秒级自动通过）。

   ⚠️ 致命避坑第一条：权限与事件回调配置完成后必须「发布版本」！飞书的应用权限与长连接事件路由不发布版本就完全不生效。若后续对权限、事件或回调有任何改动，也必须再次进入此页面发布新版本（升级小版本号如 1.0.1）才能生效。

2. 第二幕：安放你的多维表格数据家园（拿 Token & Table ID）

1. 创建官方求职中枢模板副本：打开模板链接 Auto-JobHunter 求职中枢官方模板 → 点击右上角「...」→「创建副本」到你自己的飞书云空间。

   该模板内置了岗位总表、简历库、真题面经库等全部字段与视图逻辑，无需手动新建。

2. 必须执行：把应用加为可编辑协作者！ 打开你刚保存的副本表格 → 点击右上角「分享」按钮 → 搜索你的应用名（如 求职助手）→ 将权限设置为「可编辑」。

   ⚠️ 致命避坑第二条：不加协作者会报 403 权限拒绝！多维表格具备严格数据隔离，即便拥有 App Token，若未显式加为协作者，机器人也无法读取或写入任何数据。

3. 提取 App Token：查看浏览器中该表格的 URL 地址栏，/base/ 后面那一串大约 27 位的字符即为 App Token。

   https://xxx.feishu.cn/base/【这里就是你的_FEISHU_APP_TOKEN】?table=...

4. 提取各表 Table ID：在表格左侧（或底部）点击切换不同数据表，查看地址栏 table= 之后、&view= 之前的 tbl 开头字符串：

   https://xxx.feishu.cn/base/AppToken?table=【这里就是你的_TABLE_ID (tbl开头)】&view=...

   • 点击「岗位数据汇总表」➔ 提取 FEISHU_TABLE_ID_JOBS（形如 tblnioUMCsG9Pra9）
   • 点击「我的简历库」➔ 提取 FEISHU_TABLE_ID_RESUMES（形如 tblxxxxxxxx）
   ※ 避坑提示：仅复制 table= 到 &view= 中间那一段（形如 tblnioUMCsG9Pra9，若末尾无 &view= 则复制至结尾），切勿把 &view=... 一并复制进去。

3. 第三幕：客户端参数装配与一键自检

1. 打开桌面端 App → 顶部进入「配置大盘」→「系统底层配置」。
2. 展开「飞书」分组，把前面拿到的 5 个核心值对应填入：
   • FEISHU_APP_ID：粘贴 cli_xxxxxxxx
   • FEISHU_APP_SECRET：粘贴你的应用 Secret
   • FEISHU_APP_TOKEN：粘贴多维表格文档 Token
   • FEISHU_TABLE_ID_JOBS：粘贴岗位总表 Table ID
   • FEISHU_TABLE_ID_RESUMES：粘贴简历库 Table ID
3. 点击右上角「保存配置」。系统支持热更新，后台长连接会自动使用新凭证重连。
4. 点击配置大盘的「飞书集成中心」分组右上方的「一键检测连通性」按钮，预期 6 项全绿：

   ✓ 连通性测试全通：凭证合法、多维表格文档与数据表可读写、机器人能力正常、WebSocket 长连接在线！

4. 第四幕：拉群唤醒求职秘书 & 首次对话

1. 把机器人拉入群聊：打开你想用来接收战报和下指令的飞书群 → 点击群设置 →「群机器人」→「添加机器人」→ 选择你创建的自建应用。
2. 在群里首次测试连通：在群中发送 @求职助手 ping，机器人预期将在毫秒内回复 🏓 pong！
3. 配置战报推送群：在配置大盘「飞书集成中心」分组下方的「接收群 Chat ID」下拉列表中，选中该群。
4. 开启智能助理求职生活：此后，所有岗位的自动抓取、初评打分都会生成精美互动战报卡片推送到群；你还可以随时用自然语言指挥：
   • @求职助手 看看整体数据
   • @求职助手 帮我找一下 字节 的 后端 岗位
   • @求职助手 把这条岗位改成已投递

5. 避坑指南与排错 FAQ（按高频发生排序）