#Slack 集成

Slack 集成提供两种互相独立的连接：

• 组织 Slack 工作区：在 Slack 里创建任务、发送任务回链、展开任务链接预览，并向已连接个人账号的成员投递通知。
• Agent 机器人：把一个 HiFox Agent 绑成 Slack 机器人，在单聊、频道 @ 和线程中对话。

连工作区不会自动创建 Agent 机器人；连 Agent 机器人也不会打开工作区任务能力。两者可以同时使用，但需要分别配置。

#Slack 集成能做什么？

绑定组织 Slack 工作区后，你可以：

• 用 slash 命令、全局快捷方式或消息快捷方式创建 HiFox 任务；
• 在消息里提到任务编号时，让 HiFox 在线程里回复任务链接（任务回链，可关）；
• 分享任务链接时展开预览卡片（链接预览，可关）；
• 让已连接个人 Slack 账号的成员，以应用私信接收收件箱通知。

绑定 Agent 机器人后，你可以：

• 把一个 HiFox Agent 连接成 Slack 机器人；
• 在 Slack 单聊中直接和 Agent 对话；
• 在频道或私有频道中 @ 机器人，让 Agent 在线程中回复；
• 可选：对频道消息加表情触发，或按频道打开普通消息触发；
• 在已经由 Agent 参与的 Slack 线程中继续回复；
• 使用 Slack Assistant 面板时，让 Agent 运行状态显示为 Thinking；
• 在 HiFox 外部应用集成页或 Agent 集成页查看、管理、断开 Slack 机器人。

Agent 机器人连接的是 Agent 外部会话，不会自动创建 HiFox 任务。如果对话中形成了需要分配、追踪或验收的工作，建议把它整理成 HiFox 任务，再指派给 Agent。

#绑定 Slack 工作区

组织 owner 或 admin 可以绑定 Slack 工作区。

1. 进入组织后，打开 外部应用集成。
2. 打开 Slack 详情页。
3. 在 绑定 Slack 工作区 中点击 绑定。
4. 在弹出的 Slack 授权窗口中选择工作区并完成安装。

一个 Slack 工作区同时只能绑定一个 HiFox 组织。如果该工作区已被另一个组织占用，需要先在那边断开后再试。

绑定后，共享应用支持：

• 用 slash 命令、全局快捷方式或消息快捷方式创建任务；创建时可以选择当前身份有权访问的空间、任务类型和状态，其他可用字段也会按当前成员权限提供；
• 创建任务时选择的图片、视频等附件可以随任务带入正文，并在任务中查看；
• 任务回链：Slack 消息提到任务编号时，HiFox 在消息串中回复任务链接；可在 Slack 集成页关闭；
• 链接预览：分享任务链接时展开预览卡片；关闭后所有任务链接都只显示为普通链接，HiFox 自己发出的也不例外。

断开工作区会停止该工作区上的任务创建、任务回链、链接预览和成员通知。已有 HiFox 任务和 Slack 消息不会被删除。

#从 Slack 更新任务

在 Slack 的任务卡片或详情面板中，可以更新任务的状态、优先级、处理人、标签、开始日期和截止日期。变更会同步回 HiFox；实际可编辑的字段仍受当前成员身份和权限约束。

#接收 Slack 通知

Slack 通知是收件箱的可选外发通道。要真正收到私信，下面两步都要齐：

1. 组织已经绑定 Slack 工作区；
2. 你已经连接自己的 Slack 账号。

个人连接可以在这些位置完成：

• 设置 → 通知 → Slack；
• 设置 → 第三方账号绑定；
• Slack 集成页的 我的 Slack 账号。

连接成功后，Slack 通道会自动开启，应用会给你发一条确认私信。这条私信是通路可用的信号；如果没收到，先检查工作区是否仍已绑定，以及 Slack 是否允许该应用给你发私信。

开启后可以按组开关：

• 指派
• 状态变更
• 评论与回复
• 提及
• Agent 活动

关掉某一组只停 Slack 私信，收件箱仍会记录。如果关掉收件箱对应组，两边都不会再出。

开启后只投递之后产生的事件，不会回放收件箱里已经积压的通知。个人连接按组织生效；如果你同时属于多个组织，需要分别连接。

状态变更私信会写清任务编号、前后状态和操作人。任务编号可点进任务；当前状态加粗；箭头使用 →。例如：

任务 HF-12082 状态变更：待开始 → 进行中，操作人：Zero

#任务绑定的话题

从 Slack 让 Agent 创建任务时，可以同时绑定当前话题。绑定后，任务评论和该话题消息会同步。具体方向和哪些评论会出去，以线上为准。

任务详情的资源区可以看到已绑定话题（例如「已绑定 {{channel}} 里的话题」），也可以停止同步。停止同步不会删除任务或 Slack 里的历史消息。

绑定话题之后，状态变更也可以发到该话题。那是另一条通知，见后文；不要把评论同步和状态变更当成同一件事。

话题消息和上面的收件箱私信不是同一套模板。

#在自动化工作流中连接 Slack

自动化工作流里的 Slack 动作（例如发消息）需要单独连接，和上面的组织工作区、Agent 机器人都不是同一条链路。也不要把这里和空间里的时间表 / 状态 / 评论关键词 / Webhook 自动化混在一起。

连接 Slack 动作时，认证方式按优先级出现：

私有化或未配置平台凭证时，「OAuth2（推荐）」不会出现，不是点了才报错的假开关。

当前 Slack 在工作流里只作为动作可用。Slack 触发器（Events API）尚未打通，不能把 Slack 事件当成工作流起点。

工作流连接和组织级 Slack 集成共用同一个 Slack 应用。同一工作区里两侧会拿到同一个 bot token；一侧卸载或撤回授权，会影响另一侧。工作流连接是空间级资源，不受「一个 Slack 工作区只能绑一个组织」限制。

#连接 Agent 机器人前需要准备什么？

一个 Agent 同一时间只能绑定一个 Slack 机器人。已经绑定 Slack 的 Agent 不会再出现在可选列表中。

#从哪里进入？

你可以从两个位置配置 Agent 机器人：

• 进入组织后，打开 外部应用集成，在 Slack 卡片上点击 设置 或 管理；
• 进入某个 Agent 的详情页，在 集成 页签中配置 Slack，这种方式会直接绑定当前 Agent。

Slack 卡片会根据当前状态显示不同信息：

打开弹窗后，标题为 连接 Slack。如果还没有可绑定的 Agent，弹窗会提示先创建 Agent。

#获取 Slack App Configuration Refresh Token

连接 Agent 机器人前，需要先在 Slack API 后台生成 App Configuration Token。

操作步骤：

1. 打开 api.slack.com/apps。
2. 进入 Your App Configuration Tokens。
3. 生成一个新的 App Configuration Token。
4. 复制其中的 Refresh Token。
5. 回到 HiFox，把 Refresh Token 粘贴到 Slack 集成弹窗中。

这个令牌只用于创建和安装 Slack App。HiFox 会用它自动配置应用，不需要你手动填写事件订阅 URL、OAuth 回调 URL 或权限范围。

#连接 Slack 机器人

在 HiFox 中连接 Slack 机器人的步骤：

1. 打开 连接 Slack 弹窗。
2. 点击 绑定 Agent。
3. 选择要绑定的 Agent。
4. 可选：填写 Slack 应用名称。不填写时，默认使用 Agent 名称；名称最长 35 个字符。
5. 粘贴 App Configuration Refresh Token。
6. 点击 创建并安装。
7. 在弹出的 Slack 授权窗口中选择工作区并授权安装。
8. 回到 HiFox，等待机器人状态变为 已连接。

安装过程中，HiFox 会显示安装进度。授权完成后，Slack 窗口会通知 HiFox 刷新状态；如果没有立即刷新，也可以稍等几秒或重新打开弹窗查看。

安装成功后，HiFox 会尽量给安装用户发送一条欢迎私信。欢迎消息发送失败不会影响集成本身。

#HiFox 会自动配置什么？

创建 Slack 机器人时，HiFox 会自动创建 Slack App，并配置：

• 应用名和机器人显示名；
• App Home Messages tab；
• Slack Assistant View；
• OAuth redirect URL；
• Events API Request URL；
• 机器人所需权限；
• 单聊、频道提及、频道消息和 Assistant 相关事件订阅。

当前自动配置的权限重点用于读取提及和消息、发送回复、接入单聊和 Assistant。你通常不需要在 Slack 后台手动修改这些配置。

#在 Slack 中怎么使用？

#单聊机器人

安装完成后，可以直接给 Slack 机器人发私信。

第一次单聊时，HiFox 会为这个 Slack 对话创建对应的 Agent 会话。之后你在同一个单聊里继续发送消息，Agent 会基于这个会话继续回复。

#在频道中 @ 机器人

在频道或私有频道中，可以 @ 机器人并输入问题或指令。这是默认触发方式。

HiFox 会把 @ 后面的文本作为用户消息发送给 Agent。对话频道里，群消息 @ 会在对应线程回复；已经在线程里 @ 则回在当前线程。

#可选：表情触发、普通消息触发

在 Agent 的 Slack 集成里，每条触发一行，可开可关；悬停会出现「设置」。开关名称以线上为准，常见有：

• 频道内被 @ 到（默认）
• 频道内 Emoji 表情触发
• 频道内消息直接触发（必须指定频道，不能对全部频道生效）

表情触发：对话频道里对群消息加表情会新开 thread 回复，并带上该消息附近上下文；已经在 thread 里加表情则回在当前 thread。触发表情在设置里选择。

普通消息触发：所选频道里的每条消息都会触发一次 Agent，无需 @，其他应用发的消息同样会触发。高级设置里可以打开「Slack 话题下有新消息时继续触发」。

#在线程中继续回复

当 Agent 已经参与某个 Slack 线程后，你可以在线程里继续回复。只要这是已有的 Agent 线程，后续回复不需要每条都重新 @ 机器人。

如果没有打开普通消息触发，普通频道里单独发消息、且不是 Agent 已参与的线程，不会触发 Agent。

#使用 Slack Assistant 面板

Slack App 会启用 Assistant 相关能力。使用 Assistant 面板时，Agent 运行过程中会尽量在 Slack 里显示 Thinking 状态。

#连接后会发生什么？

连接成功后，Slack 中的消息会进入 HiFox 对应 Agent 的外部会话。

常见流程是：

1. 用户在 Slack 单聊、Assistant 面板，或按已开启的触发方式在频道中 @、加表情或发消息；
2. HiFox 接收 Slack 事件并验证请求；
3. HiFox 找到或创建对应 Slack 会话；
4. 用户消息写入会话，并触发 Agent 运行；
5. Agent 生成回复；
6. 回复通过 Slack 集成发回原对话或线程。

当前回复以文本消息发送。Slack 中的编辑消息、加入频道、修改话题等非普通消息事件不会触发 Agent；机器人或应用自己发出的消息也会被忽略，避免循环回复。

#管理和断开 Slack 机器人

回到 Slack 集成弹窗后，可以查看已连接的机器人列表。

每个机器人会显示：

• 绑定的 Agent；
• Slack 应用名称；
• Slack 工作区信息；
• 当前状态。

需要停止使用时，可以在机器人列表中选择 断开。断开后，这个 Agent 不再通过该 Slack 机器人收发消息；已有 HiFox 会话和历史消息不会因此变成 Slack 里的新消息或自动删除 Slack 历史。

#权限和安全

通常规则是：

• 组织 owner / admin 可以绑定或断开 Slack 工作区，并调整任务回链和链接预览；
• 组织成员可以为自己拥有或有权限使用的 Agent 创建和管理 Slack 机器人；组织 owner / admin 可以管理组织中的所有 Agent Slack 机器人；
• 每个 Slack 机器人绑定一个 Agent；
• Slack bot token、signing secret、client secret 等凭证会加密保存；
• Slack webhook 请求会验证签名，防止伪造事件；
• App Configuration Refresh Token 只应通过 HiFox 的连接弹窗提交，不要粘贴到任务评论、聊天消息或公开文档中。

建议使用权限清晰的 Slack 管理账号完成安装，并定期检查 Slack App 的安装状态和权限范围。

#常见状态

#常见问题

#为什么需要 App Configuration Refresh Token？

HiFox 使用它自动创建和配置 Slack App。这样你不需要手动复制 Events API Request URL、OAuth callback、权限 scope 或事件订阅配置。组织工作区绑定不使用这个令牌。

#为什么没有可选 Agent？

可能还没有创建 Agent，或者所有可用 Agent 都已经绑定了 Slack。一个 Agent 只能绑定一个 Slack 机器人。

#Slack 应用名称可以不填吗？

可以。不填写时，HiFox 会默认使用 Agent 名称。Slack 应用名称最多 35 个字符，过长会被截断。

#频道里的普通消息会触发 Agent 吗？

默认不会。频道里要先 @ 机器人，或者在已有 Agent 线程中继续回复。如果在该频道打开了 频道内消息直接触发，普通消息也可以触发；打开了表情触发，对消息加指定表情也可以触发。先看绑定是否仍连接，再看该频道开的是 @、表情还是任意消息。

#断开 Slack 机器人会删除 Slack App 吗？

HiFox 会断开这个 Agent 和 Slack 机器人的绑定。是否还需要在 Slack 后台移除或管理对应 App，可以根据团队的 Slack 管理规则处理。

#Slack 消息会变成 HiFox 任务吗？

Agent 机器人不会自动把消息变成任务。组织工作区绑定后，可以用 slash 命令、全局快捷方式或消息快捷方式主动创建任务。需要状态、负责人、评论和验收标准的工作，建议创建 HiFox 任务，再指派给 Agent。

#为什么收不到 Slack 通知？

先确认组织已绑定 Slack 工作区，再确认你已连接个人 Slack 账号，并且对应通知组已开启。连接成功后应先收到一条确认私信；开启通道不会回放收件箱里已有的通知。