飞书/Lark 集成

AgentHub 把飞书/Lark 作为协作入口：机器人消息、事件订阅、交互卡片，以及 H5/工作台入口。产品登录和账号绑定仍归 TokenDance ID。

集成边界

flowchart LR
  Client["飞书/Lark 客户端"] --> App["AgentHub 机器人、卡片、H5"]
  App --> Gateway["Feishu Integration Gateway"]
  Gateway --> Hub["AgentHub Hub Server"]
  Hub --> ID["TokenDance ID"]
  ID --> Binding["飞书账号绑定"]

飞书应用应聚焦协作入口：

• 接收单聊消息和群聊 @；
• 发送机器人回复和任务卡片；
• 处理卡片按钮回调；
• 在 H5/工作台中打开 AgentHub；
• 把身份和绑定交给 TokenDance ID。

生产入口

生产环境应保留 HTTPS Webhook Gateway 作为稳定事件入口。建议把消息事件和卡片动作分成独立路由：

POST /integrations/feishu/events
POST /integrations/feishu/card-actions

Webhook 入口负责 URL challenge、签名/加密校验、事件去重、token 缓存、消息解析和快速确认。耗时的 AgentHub 工作应异步入队。

SDK 长连接适合企业自建应用开发和内部测试，但不应成为唯一的生产入口，也不适合作为未来跨租户事件路径的唯一方案。

应用设置清单

声明飞书/Lark 集成可供用户测试前，先按这张清单检查。真实 app id、secret、tenant id、callback token 和审批截图不要进入公开仓库。

必要事件

MVP 事件集合应保持克制：

群聊默认只响应 @ 机器人。除非产品需求和安全审查明确通过，否则不要申请读取全群消息的敏感权限。

公开安全 Payload 示例

URL challenge 应在业务逻辑前完成，并返回平台要求的 challenge body。示例只展示形状：

{
  "type": "url_verification",
  "challenge": "challenge_string"
}

{
  "challenge": "challenge_string"
}

消息事件示例：

{
  "schema": "2.0",
  "header": {
    "event_id": "evt_123",
    "event_type": "im.message.receive_v1",
    "tenant_key": "tenant_123"
  },
  "event": {
    "message": {
      "message_id": "msg_123",
      "chat_id": "chat_123",
      "message_type": "text",
      "content": "{\"text\":\"@AgentHub review docs\"}"
    },
    "sender": {
      "sender_id": {
        "open_id": "ou_xxx",
        "union_id": "on_xxx"
      }
    }
  }
}

卡片动作示例：

{
  "schema": "2.0",
  "header": {
    "event_id": "evt_card_123",
    "event_type": "card.action.trigger"
  },
  "event": {
    "operator": {
      "open_id": "ou_xxx"
    },
    "action": {
      "value": {
        "action": "approve_run",
        "taskId": "task_123",
        "approvalId": "approval_123"
      }
    }
  }
}

快速确认响应应轻量，耗时任务入队：

{
  "ok": true,
  "queued": true,
  "requestId": "req_123"
}

如果用户未绑定 TokenDance ID，返回绑定卡片，而不是创建 Hub task：

{
  "card": {
    "title": "绑定 TokenDance ID",
    "actions": [
      {
        "type": "button",
        "label": "继续绑定",
        "url": "https://id.example.invalid/bind/feishu?state=opaque_state"
      }
    ]
  }
}

这些示例不得替代真实平台签名、加密、challenge 和卡片 schema 校验。实现时以飞书/Lark 官方文档和 AgentHub 所属仓库的 schema 为准。

MVP 验收标准

飞书/Lark MVP 不是"机器人能收到消息"就算完成。至少要满足以下条件：

卡片和动作

卡片是 AgentHub 在飞书内的主要交互形态：

• 任务状态卡片；
• 确认、重试、取消、查看详情动作；
• 未绑定用户的 TokenDance ID 绑定卡片；
• 运行中、已完成、失败、需要输入等运行状态卡片。

卡片动作只应携带短 action id 和业务对象 id。不要在卡片 payload 中放 secret、bearer token、完整 prompt 或敏感工作区上下文。

H5 和工作台

飞书 H5/工作台入口可以在飞书客户端内打开 AgentHub，但它不是第二套登录系统。

如果用户尚未绑定，应展示 TokenDance ID 绑定路径。飞书 JSAPI 可以增强客户端内体验，但最终的产品身份和授权必须回到 TokenDance ID 与 AgentHub Hub Server 权限。

绑定闭环

推荐的用户映射流程：

1. 飞书事件带着租户和用户上下文进入 Gateway。
2. Integration Gateway 查找该飞书用户对应的 TokenDance ID 绑定。
3. 如果没有绑定，机器人返回绑定卡片。
4. 用户完成 TokenDance ID 登录和飞书账号绑定。
5. AgentHub 拿到 TokenDance ID sub，再按 Hub Server 权限执行。

AgentHub Desktop 和 Web 客户端不应保存飞书 access token；飞书 open_id、user_id 或 union_id 也不能成为产品用户主键。

安全清单

• Verification Token、Encrypt Key、App Secret 和 tenant token 只放在服务端 secret storage。
• 进入业务处理前完成签名校验，并对加密事件做解密。
• 事件和卡片回调都必须在 3 秒内确认。
• im.message.receive_v1 用 message_id 去重；其他事件在可用时用 event id 去重。
• 日志记录事件类型、message id、event id、tenant、chat id 哈希、action id、耗时、结果和飞书错误码；默认不记录消息全文。
• 飞书 OAuth、refresh token 和账号绑定归 TokenDance ID。

下一步

• 使用系统架构文档确认 Integration Gateway 与 AgentHub Hub Server 的边界。
• 在 AgentHub runtime endpoints、卡片 schema 和绑定 callback 证据发布前，把飞书机器人配置视为开发中能力。
• 在 AgentHub 实现 backlog 中跟踪生产权限范围和审核材料。