> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书集成

> Zeus 飞书数字分身 - 自动回复与消息同步

# 飞书数字分身集成

Zeus 支持与飞书 (Feishu/Lark) 深度集成，创建你的数字分身，实现自动回复、消息同步和智能助手功能。

## 概述

飞书数字分身是一个运行在飞书上的 AI 智能体，能够：

* **自动回复消息** - 私聊和群聊中代表你回复
* **智能激活策略** - 支持 @ 触发或全部消息回复
* **SSE 流式更新** - 实时更新消息卡片，展示思考过程
* **工具调用可视化** - 在消息卡片中展示工具执行状态
* **复用 Zeus 能力** - 继承完整的 Agent 能力和人格设定

## 架构设计

```mermaid theme={null}
flowchart TD
    subgraph Gateway["Zeus Digital Twin Gateway"]
        FeishuCh["飞书 Channel"]
        SlackCh["Slack Channel"]
        OtherCh["其他渠道 Channel"]

        subgraph Router["Channel Router"]
            Normalize["消息规范化 (normalize)"]
            Activation["激活策略 (mention / always)"]
            SessionIso["会话隔离 (session per chat/user)"]
        end

        subgraph Agent["AI Agent (DeepAgents)"]
            Memory["上下文记忆 (Memory Service)"]
            Tools["工具调用 (MCP Tools)"]
            Persona["人格设定 (CORE + SOUL Prompts)"]
        end

        subgraph Response["Response Router"]
            SSE_update["SSE → 消息卡片更新"]
            Format["格式转换 (markdown → 飞书 post)"]
            Reply["回复发送"]
        end

        FeishuCh --> Router
        SlackCh --> Router
        OtherCh --> Router
        Router --> Agent
        Agent --> Response
    end
```

## 快速开始

### 1. 创建飞书应用

1. 访问 [飞书开放平台](https://open.feishu.cn/app) 创建应用
2. 添加 **机器人** 能力
3. 配置权限：
   * `im:message` - 获取与发送消息
   * `im:message.group_at_msg` - 接收群 @ 消息
   * `im:chat` - 获取群信息
4. 获取 `App ID` 和 `App Secret`

### 2. 配置事件订阅

在飞书开放平台配置事件订阅：

* **请求地址**: `https://your-domain.com/api/channels/feishu/webhook`
* **订阅事件**: `im.message.receive_v1` (接收消息)

### 3. 环境变量配置

在 `.env` 文件中配置以下环境变量：

* `FEISHU_APP_ID` - 飞书应用 App ID
* `FEISHU_APP_SECRET` - 飞书应用 App Secret
* `FEISHU_VERIFICATION_TOKEN` - 验证 Token
* `FEISHU_ENCRYPT_KEY` - 消息加密密钥（可选）
* `FEISHU_DM_ACTIVATION` - 私聊激活策略（`always` 或 `mention`）
* `FEISHU_GROUP_ACTIVATION` - 群聊激活策略（`always` 或 `mention`）
* `FEISHU_ALLOWED_USERS` - 用户白名单（可选，逗号分隔）
* `FEISHU_ALLOWED_CHATS` - 群聊白名单（可选，逗号分隔）

### 4. 发布应用

完成配置后，在飞书开放平台发布应用，即可开始使用。

***

## 激活策略

借鉴 [OpenClaw](https://docs.openclaw.ai) 的设计，支持灵活的激活策略：

| 策略        | 说明      | 适用场景     |
| --------- | ------- | -------- |
| `always`  | 所有消息都回复 | 私人助手、专属群 |
| `mention` | 仅 @ 时回复 | 公共群、多人协作 |

支持按场景独立配置：

* **私聊策略** - 默认 `always`（私聊总是回复）
* **群聊策略** - 默认 `mention`（群聊仅 @ 回复）
* **白名单** - 可配置允许的用户和群聊列表，为空时全部允许

***

## SSE 流式消息同步

Zeus 支持将完整的 SSE 消息流同步到飞书，实现类似 Web 端的实时体验。

### 消息类型映射

| SSE 消息类型                | 飞书展示     |
| ----------------------- | -------- |
| `TextMessage`           | 消息内容实时更新 |
| `ToolCallMessage`       | 显示工具调用状态 |
| `ToolCallResultMessage` | 更新工具执行结果 |
| `CompleteMessage`       | 最终完成状态   |
| `ErrorMessage`          | 错误提示     |

### 实现原理

```mermaid theme={null}
sequenceDiagram
    participant SSE as SSE Stream (Zeus)
    participant Feishu as 飞书 API

    SSE->>Feishu: TextMessage (chunk 1) → 创建消息卡片 (POST)
    SSE->>Feishu: TextMessage (chunk 2) → 更新消息卡片 (PATCH)
    SSE->>Feishu: TextMessage (chunk 3) → 更新消息卡片 (PATCH)
    SSE->>Feishu: ToolCallMessage → 更新卡片：显示工具调用
    SSE->>Feishu: ToolCallResultMessage → 更新卡片：显示结果
    SSE->>Feishu: TextMessage (final) → 更新消息卡片 (PATCH)
    SSE->>Feishu: CompleteMessage → 最终更新（移除加载态）
```

### 效果展示

消息卡片会实时更新，展示完整的思考和执行过程：

```
┌─────────────────────────────────────┐
│ Zeus AI                        🔵    │
├─────────────────────────────────────┤
│ 根据搜索结果，今天的主要新闻有:      │
│ 1. AI 技术新突破...                  │
│ 2. 科技公司财报...                   │
│─────────────────────────────────────│
│ 🔧 工具调用:                         │
│ ✅ web_search                        │
└─────────────────────────────────────┘
```

***

## API 端点

### Webhook 接收

`POST /api/channels/feishu/webhook`

处理的事件类型：

* `url_verification` - URL 验证（首次配置）
* `im.message.receive_v1` - 接收消息

***

## 消息卡片模板

推荐使用飞书消息卡片展示 AI 回复，支持：

* 状态指示器（思考中/回复中/完成）
* Markdown 内容渲染
* 工具调用可折叠展示
* 错误信息提示

***

## 高级功能

### 计划中的功能

| 功能        | 优先级 | 说明                             |
| --------- | --- | ------------------------------ |
| 消息记忆      | P0  | 使用 MemoryService，按 chat\_id 隔离 |
| 群聊上下文     | P0  | 记住群聊中的对话上下文                    |
| @ 回复      | P0  | 群聊中回复时自动 @ 提问者                 |
| 消息卡片      | P1  | 使用飞书消息卡片展示复杂内容                 |
| 延迟回复      | P1  | 模拟思考时间，更自然                     |
| 日程集成      | P2  | 集成飞书日历，自动回复"我在开会"              |
| 文件处理      | P2  | 处理图片、文档等附件                     |
| 离线模式      | P2  | 设置"勿扰"时自动回复                    |
| Cron 主动消息 | P3  | 定时发送日报、提醒等                     |

### 与其他渠道集成

飞书渠道设计遵循通用的 Channel 抽象，未来可扩展支持：

* Slack
* Discord
* 企业微信
* Telegram
* 钉钉

***

## 安全考虑

### 签名验证

建议启用飞书事件签名验证，使用 SHA-256 HMAC 对请求进行签名校验，确保消息来源可信。验证时需要检查请求头中的 `X-Lark-Request-Timestamp` 和 `X-Lark-Request-Nonce`。

### 白名单机制

* 支持用户白名单 (`allowed_users`)
* 支持群聊白名单 (`allowed_chats`)
* 未配置时默认全部允许

### 敏感操作保护

对于重大决策、财务、法律等敏感问题，数字分身会明确表示需要本人确认。

***

## 参考资料

* [飞书开放平台文档](https://open.feishu.cn/document)
* [飞书消息 API](https://open.feishu.cn/document/server-docs/im-v1/message/create)
* [飞书消息卡片搭建工具](https://open.feishu.cn/tool/cardbuilder)
* [OpenClaw 多渠道设计](https://docs.openclaw.ai/channels)