跳转到主要内容

​
飞书数字分身集成

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

​
概述

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

​
架构设计

​
快速开始

​
1. 创建飞书应用

  1. 访问 飞书开放平台 创建应用
  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 的设计，支持灵活的激活策略：
策略说明适用场景
always所有消息都回复私人助手、专属群
mention仅 @ 时回复公共群、多人协作
支持按场景独立配置：
  • 私聊策略 - 默认 always（私聊总是回复）
  • 群聊策略 - 默认 mention（群聊仅 @ 回复）
  • 白名单 - 可配置允许的用户和群聊列表，为空时全部允许

​
SSE 流式消息同步

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

​
消息类型映射

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

​
实现原理

​
效果展示

消息卡片会实时更新，展示完整的思考和执行过程： 
┌─────────────────────────────────────┐
│ 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)
  • 未配置时默认全部允许

​
敏感操作保护

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

​
参考资料