飞书集成
飞书集成提供两条互相独立的能力：
- 组织飞书助手：在飞书里粘贴任务链接时渲染权限感知的预览卡片，并向已关联飞书账号的成员发送通知。
- Agent 智能体：通过二维码把一个 HiFox Agent 连接为飞书智能体，在飞书里收发消息。
连接组织助手不会自动创建 Agent 智能体；扫码绑定 Agent 也不会打开任务链接预览或组织级飞书通知。两者可以同时使用，但需要分别配置。
组织飞书助手
组织 owner 或 admin 可以在 外部应用集成 里连接组织级飞书自建应用。连接后，这个应用就是成员在飞书里看到的 HiFox 助手。
任务链接预览
在飞书里粘贴 HiFox 任务链接时，助手会把它渲染成预览卡片。卡片可以直接点进任务，并会显示任务创建人。
预览和通知的鉴权已经拆开：
- 公开空间：不绑定个人飞书账号也可以渲染预览。
- 私有空间：未绑定个人账号时不可预览，需要先授权并关联个人账号。
- 通知不变：仍须组织助手已连接，并且个人飞书账号已关联，才能收到飞书私聊。预览能看，不等于能收通知。
预览依赖飞书开放平台的这些配置：
- 应用已发布正式版本；测试版本不会渲染预览；
- 回调用长连接接收；
- 订阅
url.preview.get； - 已登记 URL 规则。一条通配路径即可，例如
app.hifox.com/**，不必为任务详情、收件箱、我的任务等路径分别配置。
应用可用范围仍是飞书侧门槛：不在范围内的人，飞书不会向 HiFox 发起预览请求。公开空间预览不再额外要求个人账号绑定；私有空间仍要绑定。通知仍要求个人账号已关联。
飞书通知
飞书通知是收件箱的可选外发通道。要真正收到私聊，需要：
- 组织助手已经连接；
- 你的飞书账号已经关联。
入口在 设置 → 通知 → 飞书。也可以在 设置 → 第三方账号绑定，或飞书集成页的 我的飞书账号 完成关联。
如果飞书邮箱和 HiFox 邮箱一致，目录同步会自动匹配。两边邮箱不一致时，需要走显式账号关联。
通知分组与 Slack 相同：指派、状态变更、评论与回复、提及、Agent 活动。关掉某一组只停飞书私聊，收件箱仍会记录；关掉收件箱对应组则两边都不会再出。开启后只投递之后产生的事件，不会回放收件箱积压。
助手失效时，这里的开关会保留，重连后再生效。断开组织应用会立刻停止预览和通知；飞书侧的自建应用本身不受影响，之后可以用同一套凭证重新连接。
任务绑定的话题
从飞书让 Agent 创建任务时，可以同时绑定当前话题。绑定后，任务评论和该话题消息会同步；Agent 触发设置里对应说明是「飞书话题下的消息自动同步到任务评论」。哪些评论会写回飞书，以线上为准。
任务详情可以看到已绑定话题（例如「已绑定“某群”群里的话题」），也可以停止同步或恢复同步。停止同步不会删除任务或飞书里的历史消息。
绑定话题之后，状态变更也可以发到该话题。那是另一条通知，不要和评论同步写成同一件事。
新连接的飞书机器人，默认开启话题 ↔ 任务同步。已经连上的机器人不会被这次默认值改掉。
话题消息和组织助手私聊通知不是同一套模板。
飞书智能体能做什么？
- 将一个 HiFox Agent 连接为飞书智能体；
- 在飞书中向 Agent 发送文本、富文本、图片和视频附件消息；
- 让 Agent 的回复返回原飞书会话；
- 分别控制是否响应私聊、群里被 @、表情触发和指定群的普通消息；
- 在 HiFox 中查看、调整或断开已有绑定。
飞书智能体适合临时提问、信息查询、方案讨论和轻量协作。如果对话中形成了需要持续跟踪、协作或验收的工作，建议创建 HiFox 任务并指派给 Agent。
从相关飞书会话创建或编辑任务时，视频可以作为可访问附件带入，并嵌入任务正文。普通飞书消息不会因此自动变成 HiFox 任务。
新开对话
在已有的飞书单聊、群聊或话题会话中，发送 /new 可以开始一个新的 Agent 会话：
也可以把新会话的首条提示词写在命令后：
/new 只会新开 Agent 会话，不会自动创建 HiFox 任务。
连接 Agent 前需要准备什么？
普通成员只能选择自己拥有或有权限使用的 Agent，不能选择无权限的 Agent。
一个 Agent 同一时间只能绑定一个飞书入口。已经绑定飞书的 Agent 不会再次出现在可选列表中。
整个 Agent 连接过程通过飞书二维码授权完成，不需要为智能体单独创建自建应用，也不需要填写 App ID、App Secret 或配置组织授权。组织助手使用的是另一条自建应用链路。
从外部应用集成页连接
- 进入 HiFox 组织，打开 外部应用集成。
- 点击飞书卡片，进入飞书详情页。
- 点击 绑定 Agent。
- 选择要绑定的 Agent。
- 等待系统生成二维码。
- 使用飞书扫描二维码，或点击二维码卡片中的 打开链接。
- 在飞书中完成智能体创建和授权。
- 返回 HiFox，等待状态变为连接成功。
选择 Agent 后，HiFox 会自动创建一次授权会话并显示二维码，不需要再点击单独的“创建”按钮。
从 Agent 页面连接
如果已经进入某个 Agent 的详情页，也可以从该 Agent 的集成区域点击飞书。系统会直接为当前 Agent 创建授权会话并显示二维码，不再要求重复选择 Agent。
扫码或打开链接后，在飞书中完成授权即可。连接成功后，该 Agent 会出现在飞书详情页的已绑定列表中。
管理已有绑定
飞书详情页会列出当前组织中已有的 Agent 绑定。你可以：
- 查看每个飞书入口绑定的 Agent；
- 添加其他尚未绑定的 Agent；
- 刷新绑定状态；
- 断开不再需要的飞书绑定。
如需控制单聊消息或群聊 @ 提及是否触发 Agent，请进入对应 Agent 的集成设置调整。
断开后，该飞书入口将停止把新消息发送给对应 Agent。需要恢复时，请重新完成二维码授权。
连接后会发生什么？
常见消息流程如下：
- 用户在飞书中向智能体发送消息；
- HiFox 接收飞书事件并找到对应绑定；
- 消息进入该 Agent 的外部会话并触发运行；
- Agent 生成回复；
- 回复通过飞书集成返回原会话。
图片会作为附件提供给 Agent。是否响应私聊、群 @、表情或指定群的普通消息，取决于该绑定的触发设置。
Agent 如何使用对话上下文
在私聊、群聊中被 @，或话题会话中触发 Agent 时，Agent 可以使用当前会话中可访问的相关消息来理解需求。不同话题保持各自独立的上下文，不会因为同在一个群里而自动混合。
可访问的历史消息、图片、引用内容和成员名称都可能帮助 Agent 理解任务；如果其中一部分内容不可用，Agent 会基于当前消息和可访问的引用继续处理。实际可访问范围仍取决于飞书授予的权限和该入口的触发设置。
默认仍是私聊和群里被 @。在 Agent 的飞书集成里，每条触发一行，可开可关；悬停会出现「设置」。开关名称以线上为准，常见有：
- 私聊
- 群里被 @ 到
- 群消息 Emoji 表情触发
- 群消息直接触发（必须指定群聊，不能对全部群聊生效）
回复落点：
- 对话群：群里 @ → 群里回；话题里 @ → 当前话题回。对群消息加表情 → 新开话题回；已经在话题里加表情 → 当前话题回。
- 话题群：无论 @ 还是表情，都回在对应话题下。新开一个话题时若打开了普通消息触发，会在该话题下回；之后话题里的普通消息不再自动回，之后 @ 仍可触发。高级设置里可以打开「飞书话题下有新消息时继续触发」。
常见状态
授权链接和二维码具有时效性。如果过期，请点击 重试 生成新的授权会话。
权限和安全
- 二维码和授权链接只用于当前一次连接流程，请勿转发给无关人员；
- 连接 Agent 智能体时，HiFox 不会要求你填写飞书 App ID 或 App Secret；
- 组织助手需要组织 owner / admin 在飞书开放平台创建自建应用，并回填 App ID 和 App Secret；
- 只有在飞书中明确完成授权后，绑定才会生效；
- 不再使用的绑定应及时断开。
常见问题
为什么没有可选 Agent？
可能还没有创建 Agent，或者所有可用 Agent 都已经绑定飞书。创建新的 Agent，或先断开不再使用的绑定后再试。
二维码为什么失效了？
每次连接使用一次性的授权会话。二维码过期、在飞书中取消授权或会话丢失后，点击 重试 即可生成新的二维码。
扫码后为什么仍显示等待授权？
请确认已经在飞书中完成最后的创建与授权步骤，而不只是打开页面。完成后稍等片刻，HiFox 会自动更新连接状态。
收不到飞书消息怎么办？
如果是 Agent 智能体收不到消息：先确认绑定仍显示为已连接，再看该群开的是私聊、群 @、表情还是任意消息。默认群聊仍需要 @ 该飞书智能体；打开了表情触发或指定群的普通消息触发后，按对应方式即可。
如果是收不到组织助手通知：先确认组织助手已连接，再确认你的飞书账号已关联，并且对应通知组已开启。邮箱对不上时，需要显式关联飞书账号。
飞书消息会自动变成 HiFox 任务吗？
不会。飞书消息进入的是 Agent 外部会话。需要跟踪状态、处理人、评论或验收标准的工作，请在 HiFox 中创建任务并指派给 Agent。