飞书集成
飞书集成提供四种能力，解决不同问题：
四种能力彼此独立，可以同时使用，但必须分别配置。飞书任务助手不是普通 Agent：它不会出现在 Agent 列表里，也不能在站内私聊或 @。
一、飞书任务助手：给每个空间一个飞书入口
飞书任务助手是系统为每个空间提供的内置助手，用来在飞书里整理需求并创建 HiFox 任务。它不是从「创建 Agent」表单建出来的。
能做什么？
- 在飞书群里 @ 机器人，根据当前话题上下文整理需求并创建任务；
- 查询、修改该空间里的 HiFox 任务；
- Agent 发出的文件会回到原来的飞书会话。
它只在飞书里工作。站内不能私聊或 @ 它，Agent 列表、处理人选择器和独立对话入口里也找不到它。它处理过的任务、评论和活动里仍会显示为执行者。
如何绑定
- 打开 外部应用集成，进入飞书详情页。
- 在 任务助手 分组里，找到你加入的空间。
- 选择 绑定飞书。
- 选择运行该空间任务助手的 Runtime。
- 在同一对话框里扫码，完成飞书机器人绑定。
每个空间只能有一个任务助手。列表显示的是你加入的空间，而不是已经存在的助手。没有绑定的空间就是待处理项。绑定对话框会同时完成创建助手和扫码，不需要先去 Agent 页新建。
绑定后可以在同一分组里编辑 Runtime、补充附加提示词，或解绑飞书、移除助手。系统已内置在飞书里创建任务的提示词；你填写的附加提示词会追加在后面。
需要把某个你自己创建的 Agent 接到飞书时，继续使用下面的飞书智能体，而不是任务助手。
二、飞书智能体：在飞书中控制 HiFox Agent
飞书智能体解决的是“在飞书中直接使用 HiFox”的问题。它把一个 HiFox Agent 连接到飞书；连接后，你可以直接在飞书里向 Agent 发消息，让 Agent 执行 HiFox 操作，而不必先打开 HiFox 页面。
能做什么？
飞书智能体可以帮助你：
- 在飞书中向 HiFox Agent 提问、讨论和下达指令；
- 创建 HiFox 任务，并把当前飞书话题绑定到任务；
- 查看和同步任务进度，包括任务状态、评论和回复等信息；
- 操作 HiFox 中的任务及其他 Agent 有权限访问的资源；
- 发送文本、富文本、图片和视频附件；Agent 发出的文件也会回到原来的飞书会话；
- 让 Agent 的回复返回原飞书会话；
- 分别控制私聊、群里被 @、表情触发和指定群的普通消息触发。
具体可操作的资源和字段取决于 Agent 的权限、连接状态以及当前启用的能力。
如果对话中形成了需要持续跟踪、协作或验收的工作，可以直接让 Agent 创建 HiFox 任务。普通飞书消息不会自动变成任务，只有创建任务时绑定了话题，后续话题消息才会按绑定规则同步到任务评论。
连接前需要准备什么？
一个 Agent 同一时间只能绑定一个飞书智能体入口。已经绑定飞书智能体的 Agent 不会再次出现在可选列表中。
飞书智能体使用二维码授权连接，不需要单独创建飞书自建应用，也不需要填写 App ID、App Secret 或配置组织授权。
连接飞书智能体
你可以从外部应用集成页或 Agent 详情页连接。
从外部应用集成页连接
- 进入 HiFox 组织，打开 外部应用集成。
- 点击飞书卡片，进入飞书详情页。
- 点击 绑定 Agent。
- 选择要绑定的 Agent。
- 等待系统生成二维码。
- 使用飞书扫描二维码，或点击二维码卡片中的 打开链接。
- 在飞书中完成智能体创建和授权。
- 返回 HiFox，等待状态变为连接成功。
选择 Agent 后，HiFox 会自动创建一次授权会话并显示二维码，不需要再点击单独的“创建”按钮。
从 Agent 页面连接
如果已经打开某个 Agent 的详情页，也可以从该 Agent 的集成区域点击飞书。系统会直接为当前 Agent 创建授权会话并显示二维码，不需要重复选择 Agent。
扫码或打开链接后，在飞书中完成授权即可。连接成功后，该 Agent 会出现在飞书详情页的已绑定列表中。
连接状态
授权链接和二维码具有时效性。过期后点击 重试，生成新的授权会话。
在飞书中使用 Agent
私聊、群聊和话题
默认情况下，智能体响应私聊和群里被 @ 的消息。不同话题保持各自独立的上下文，不会因为同在一个群里而自动混合。
在 Agent 的飞书集成设置中，每种触发方式都有单独的开关；悬停后可以看到 设置。具体开关名称以线上页面为准，常见选项包括：
- 私聊；
- 群里被 @ 到；
- 群消息 Emoji 表情触发；
- 群消息直接触发：必须指定群聊，不能对全部群聊生效。
普通群聊中，默认需要 @ 飞书智能体。开启表情触发或指定群的普通消息触发后，才会按相应方式响应。
回复会发到哪里？
- 对话群：群里 @ 会回复到群里；话题中 @ 会回复到当前话题。对群消息加表情会新开话题回复；已经在话题里加表情则回复到当前话题。
- 话题群：无论 @ 还是表情，都会回复到对应话题下。新开话题时如果开启了普通消息触发，Agent 会在该话题下回复；之后话题里的普通消息不会继续自动触发，之后的 @ 仍然可以触发。高级设置中可以开启 飞书话题下有新消息时继续触发。
Agent 如何使用上下文？
在私聊、群里被 @ 或话题会话中触发 Agent 时，Agent 可以使用当前会话中可访问的相关消息来理解需求。可访问的历史消息、图片、引用内容和成员名称，都可能帮助 Agent 理解任务。
如果部分内容不可用，Agent 会基于当前消息和可访问的引用继续处理。实际可访问范围取决于飞书授予的权限和该入口的触发设置。
新开对话
在已有的飞书单聊、群聊或话题会话中，发送 /new 可以开始一个新的 Agent 会话：
也可以把新会话的首条提示词写在命令后：
/new 只会新开 Agent 会话，不会自动创建 HiFox 任务。
创建任务并同步任务进度
飞书智能体不会把所有飞书消息自动创建成任务。需要跟踪状态、处理人、评论或验收标准时，可以在对话中让 Agent 创建 HiFox 任务。
从飞书让 Agent 创建任务时，可以同时绑定当前话题。绑定后，任务评论和该话题消息会同步；Agent 触发设置中对应的说明是“飞书话题下的消息自动同步到任务评论”。哪些评论会写回飞书，以线上行为为准。
同步有以下边界：
- 只有绑定了任务的话题会同步。普通群聊或私聊不会因为同一个机器人存在，就自动变成任务评论；
- 话题绑定生效后，话题中的消息都会同步，不要求每条消息都 @ 机器人。绑定前的历史消息只在建立绑定时进行一次受限回填；
- 停止同步后，绑定关系和已有评论仍然保留。恢复会开始新的同步阶段，停止期间产生的消息不会在恢复时自动补回；
- 只有移除绑定，话题才会释放给其他任务；
- 从话题同步进来的评论不会再次触发同一条飞书外发通知，以避免 HiFox 与飞书之间循环；
- 已关联 HiFox 账号的成员会按成员身份记录。无法确认身份的历史或外部发送者会保留为外部参与者；
- 消息中的人员 @ 提及会在飞书 → HiFox 和 HiFox → 飞书两个方向转换，单人和多人提及都支持。无法匹配人员时会保留可读原文；单个提及转换失败不会使整条消息失败，普通文本、图片和其他消息内容仍会继续同步。
任务详情可以看到已绑定话题，例如“已绑定‘某群’群里的话题”，也可以停止或恢复同步。停止同步不会删除任务或飞书里的历史消息。
绑定话题后，状态变更也可以发到该话题。状态变更是另一条通知，不要和评论同步混为一谈。
新连接的飞书机器人默认开启话题 ↔ 任务同步；已经连上的机器人不会因为这个默认值发生变化。
从相关飞书会话创建或编辑任务时，视频可以作为可访问附件带入，并嵌入任务正文。
管理和断开飞书智能体
飞书详情页会列出当前组织中已有的 Agent 绑定。你可以：
- 查看每个飞书入口绑定的 Agent；
- 添加其他尚未绑定的 Agent；
- 刷新绑定状态；
- 断开不再需要的飞书绑定。
如需控制单聊消息、群聊 @、表情或指定群普通消息是否触发 Agent，请进入对应 Agent 的集成设置调整。
断开后，该飞书入口会停止把新消息发送给对应 Agent；已有 HiFox 会话和历史消息不会因此自动删除。需要恢复时，请重新完成二维码授权。
连接成功后的消息流程通常是：
- 用户在飞书中向智能体发送消息；
- HiFox 接收飞书事件并找到对应绑定；
- 消息进入该 Agent 的外部会话并触发运行；
- Agent 生成回复或执行 HiFox 操作；
- 回复和操作结果通过飞书集成返回原飞书会话。
图片会作为附件提供给 Agent。是否响应私聊、群里被 @、表情或指定群普通消息，取决于该绑定的触发设置。
三、飞书连接器：让 HiFox 访问飞书资源
飞书连接器解决的是“HiFox 访问飞书”的问题。连接后，Agent 可以在运行过程中按授权访问飞书中的文档、表格等资源，并将这些资源用于任务处理或回复。
它和飞书智能体的方向相反：
- 飞书智能体：你在飞书中控制 HiFox Agent；
- 飞书连接器：HiFox Agent 在运行中访问飞书资源。
授权或绑定凭证
如果 Agent 需要使用飞书能力，请在 Agent 详情页打开 连接，选择飞书连接器。连接器凭证通过 HiFox 页面向导管理，不需要把 Agent 连接成飞书里的聊天智能体。
新建连接时，页面向导会引导你完成两次确认，并核对授权页面中显示的验证码或链接。这个流程具有以下特点：
- 不需要预先在飞书后台创建应用；
- 不需要在本机安装或登录飞书 CLI；
- 授权成功后，HiFox 会显示授权人的真实姓名；
- 新凭证会自动绑定到发起连接的 Agent；
- 连接完成后，第一个需要飞书资源的任务即可使用该凭证。
如果已经有可用凭证，可以直接选择 绑定已有凭证，不必再次授权。第二个 Agent 也可以复用同一条凭证；一条凭证可以绑定多个 Agent。
如果需要使用另一个飞书账号，选择 授权新账号。这会为同一个连接器创建另一个独立身份，适合需要分别管理账号权限的场景。
凭证可见范围和异常
凭证可以设置为个人、项目或组织可见。可见范围决定哪些人可以在 Agent 的连接设置中选择这条凭证；组织范围需要管理员权限。密钥类字段会保持遮罩，“去哪拿密钥”等链接以页面实际显示为准。
以下情况可能导致连接被阻止或报错：
- 凭证已过期或被吊销；
- 凭证的可见范围被缩小；
- 仍有 Agent 使用凭证时，尝试解绑或删除；
- 同一个 Agent 同时绑定了多条身份不明确的同类凭证。
页面会根据具体状态给出重新授权、调整绑定或恢复可见范围的方向。若同一个 Agent 存在冲突凭证，系统不会随机选择身份；请先解除冲突，再保留明确的凭证绑定。
连接器凭证只负责让 Agent 访问飞书资源，不会创建飞书智能体，也不会开启任务预览或组织级飞书通知。
四、组织飞书助手：预览任务并接收通知
组织飞书助手解决的是“在飞书中查看 HiFox 任务信息”的问题。连接组织级飞书自建应用后，成员可以在飞书中预览 HiFox 任务详情；已经关联个人飞书账号的成员，还可以收到 HiFox 收件箱通知。
连接组织飞书助手
组织 owner 或 admin 可以在 外部应用集成 中连接组织级飞书自建应用。组织助手使用飞书开放平台的自建应用链路，需要在飞书侧创建并配置应用，再将 App ID 和 App Secret 回填到 HiFox。
组织助手的连接和 Agent 连接器、飞书智能体是不同流程。断开组织应用只会停止 HiFox 与该应用之间的连接，不会删除飞书侧的自建应用；之后可以使用同一套凭证重新连接。
任务详情预览
在飞书里粘贴 HiFox 任务链接时，组织助手会渲染预览卡片。卡片可以直接打开任务，并显示任务创建人。
预览和通知使用不同的鉴权规则：
- 公开空间：不绑定个人飞书账号也可以渲染预览；
- 私有空间：需要先授权并关联个人飞书账号，才能预览；
- 飞书通知：仍然需要组织助手已连接，并且个人飞书账号已关联。能看到预览，不代表一定能收到通知。
要让预览生效，还需要在飞书开放平台完成以下配置：
- 应用已发布正式版本；测试版本不会渲染预览；
- 回调使用长连接接收；
- 订阅
url.preview.get； - 登记 URL 规则。一条通配路径即可，例如
app.hifox.com/**，不需要为任务详情、收件箱、我的任务等路径分别配置。
应用可用范围仍然是飞书侧的前置条件。不在应用可用范围内的人，飞书不会向 HiFox 发起预览请求。公开空间预览不再额外要求个人账号绑定；私有空间仍需要绑定。
飞书通知
飞书通知是收件箱的可选外发通道。要收到飞书私聊通知，需要同时满足：
- 组织助手已经连接；
- 你的飞书账号已经关联。
个人账号可以从以下任一位置关联：
- 设置 → 通知 → 飞书；
- 设置 → 第三方账号绑定；
- 飞书集成页的 我的飞书账号。
如果飞书邮箱和 HiFox 邮箱一致，目录同步会自动匹配。两边邮箱不一致时，需要显式关联飞书账号。
通知按以下分组控制：
- 指派；
- 状态变更；
- 评论与回复；
- 提及；
- Agent 活动。
关闭某一组，只会停止对应的飞书私聊，收件箱仍会记录该类事件。关闭收件箱中的对应分组后，收件箱和飞书两边都不会再记录或投递。开启通知后只投递之后产生的事件，不会回放收件箱中已经积压的通知。
助手暂时失效时，通知开关会保留，重连后重新生效。断开组织应用会立即停止任务详情预览和飞书通知。
权限和安全
- 二维码和授权链接只用于当前一次连接流程，请勿转发给无关人员；
- 连接飞书智能体时，HiFox 不会要求填写飞书 App ID 或 App Secret；
- 组织飞书助手需要组织 owner 或 admin 在飞书开放平台创建自建应用，并回填 App ID 和 App Secret；
- Agent 的飞书连接器使用凭证向导管理，与组织助手和飞书智能体不是同一条授权链路；
- Agent 能操作的 HiFox 资源和能访问的飞书资源受其权限与授权范围限制；
- 只有在飞书中明确完成授权后，绑定才会生效；
- 不再使用的绑定应及时断开。
常见问题
飞书任务助手、飞书智能体、飞书连接器和组织飞书助手有什么区别？
可以按数据流向理解：
- 飞书任务助手：每个空间一个系统助手，在飞书里整理需求并创建该空间的任务；
- 飞书智能体：把你自己创建的 Agent 接到飞书，从飞书发消息给 HiFox，让 Agent 创建任务、同步进度或操作 HiFox 资源；
- 飞书连接器：从 HiFox 出发，让 Agent 访问飞书文档、表格等资源；
- 组织飞书助手：把 HiFox 的任务预览和通知展示到飞书中。
任务助手不会出现在 Agent 列表里。需要给某个自建 Agent 接飞书时，使用飞书智能体。
为什么没有可选 Agent？
可能还没有创建 Agent，或者所有你有权限使用的 Agent 都已经绑定飞书智能体。创建新的 Agent，或先断开不再使用的绑定后再试。一个 Agent 同一时间只能绑定一个飞书智能体入口。
二维码为什么失效了？
每次连接使用一次性的授权会话。二维码过期、在飞书中取消授权或会话丢失后，点击 重试 即可生成新的二维码。
扫码后为什么仍显示“等待授权”？
请确认已经在飞书中完成最后的创建与授权步骤，而不只是打开页面。完成后稍等片刻，HiFox 会自动更新连接状态。
收不到飞书消息怎么办？
如果是飞书智能体收不到消息：
- 确认绑定仍显示为 已连接；
- 确认对应入口开启了正确的触发方式；
- 群聊中确认是否需要 @ 飞书智能体，或是否已开启表情触发、指定群普通消息触发。
如果是收不到组织助手通知：
- 确认组织助手已连接；
- 确认你的飞书账号已关联；
- 确认对应通知组已开启；
- 如果邮箱不一致，完成显式账号关联。
飞书消息会自动变成 HiFox 任务吗？
不会。普通消息进入的是 Agent 外部会话。需要跟踪状态、处理人、评论或验收标准的工作，请在 HiFox 中创建任务或让飞书智能体创建任务；只有在创建任务时绑定了话题，后续话题消息才会按绑定规则同步到任务评论。
组织助手和飞书智能体可以同时使用吗？
可以。组织助手负责任务详情预览和组织通知，飞书智能体负责在飞书中控制 Agent；两者需要分别完成配置。