核心用法
feishu-agent-relay 是面向飞书生态的多Agent协作编排方案，解决"用户联系一个Bot，由多个专家Bot协同响应"的复杂场景。核心架构包含三层：
1. 编排-专家架构（Orchestrator-Specialist）
- 协调者Agent（Coordinator）作为统一入口，负责任务分发
- 专家Agent（Specialist）垂直领域处理，支持主动触达用户
2. 跨Bot身份隔离机制
关键创新在于处理飞书open_id隔离特性——同一用户在不同Bot中的open_id完全不同（如协调者 Bot 中为用户 A，技术专家 Bot 中为用户 B）。系统通过中央映射表（user-mapping.json）统一管理 userid → 各Bot open_id 的映射关系。
3. 任务转接流程
用户 → 协调者Bot → sessions_send（仅传userid）→ 专家Bot → 查询映射获取自身open_id → 主动私信用户
两种部署模式：
- 单用户模式（Single-User）：个人使用，零配置，首次对话自动注册userid为"me"，5分钟完成部署
- 多用户模式（Multi-User）：团队使用，需用户手动输入User ID注册，存在身份伪造风险
显著优点
- 深度适配飞书生态：精准解决open_id隔离痛点，提供经过验证的Relay模式
- 双模式灵活部署：个人场景免配置，团队场景可扩展
- 主动消息能力：专家Bot可绕过协调者直接服务用户，降低延迟
- 完整的工程化交付：含环境变量配置、Agent SOUL模板、测试清单、错误排查指南
潜在缺点与局限性
⚠️ 关键安全缺陷（多用户模式）
用户需手动输入User ID（工号/用户名）完成注册，系统无任何身份验证机制，存在：
- 身份伪造风险（用户可冒用他人ID）
- 人工输入错误无校验
- 无审计追溯能力
明确声明：多用户模式仅限内部/个人使用，不可用于生产环境或外发应用。
其他局限：
- 必须维护多个飞书Bot应用，配置复杂度较高（约30分钟）
- 依赖外部映射表存储，需自建API服务
- 单用户模式硬编码"me"作为userid，无法区分多用户
适合人群
- 个人开发者/效率工具爱好者：单用户模式5分钟搭建个人助理系统
- 小型团队内部工具搭建者：明确知晓安全限制，用于非敏感场景
- 多Agent架构学习者：研究Bot编排、身份联邦、会话转接模式
不适合： 需要强身份认证的企业生产系统、外发C端应用、金融/医疗等敏感领域。
常规风险
1. 身份冒用风险（多用户模式）：恶意用户注册他人ID，接收私密消息
2. 数据隔离风险：映射表泄露导致全平台用户open_id暴露
3. 配置错误风险：sessionKey格式错误、Bot权限配置不当导致消息发送失败
4. 飞书API变更风险：依赖飞书开放平台，接口变更可能导致功能中断