SkillHub

feishu-agent-relay

v1.0.0

Build multi-Agent collaboration systems on Feishu (Lark). Provides complete patterns for: (1) orchestrator-specialist Agent architecture, (2) cross-Agent user identity mapping with Feishu open_id isolation, (3) Agent-to-Agent task relay via sessions_send, (4) specialist Agents proactively messaging...

Sourced from ClawHub, Authored by Glassmarbles

Installation

Please help me install the skill `feishu-agent-relay` from SkillHub official store. npx skills add Glassmarbles/feishu-agent-relay

Feishu Agent Relay

🚨 Installation: Choose Your Mode First!

⚠️ BEFORE SETUP: You must choose a deployment mode!

Mode For User ID Setup Security
Single-User Personal use Auto ("me") ✅ 5 min ✅ High
Multi-User Teams Manual entry ⚠️ 30 min ⚠️ Low

Quick Decision Guide

Choose Single-User Mode if: - ✅ Only YOU will use the Bots - ✅ Personal productivity system - ✅ Want ZERO manual configuration - ✅ Want fastest setup (5 minutes)

📖 Guide: references/single-user-setup.md

Choose Multi-User Mode if: - ✅ Multiple people will use the system - ✅ Team or organization - ✅ Need to track different users - ✅ Planning to add verification later

📖 Guide: references/feishu-bot-setup.md

⚠️ Important Limitations

Read this before using the skill:

1. Manual User ID Registration ⚠️ SECURITY LIMITATION (Multi-User Mode Only)

Current flow requires users to manually enter their User ID:

User → Bot: "你好"
Bot → User: "请告诉我您的 User ID（工号/用户名）"
User → Bot: "我的 user ID 是：user_demo_001"  ← ⚠️ MANUAL STEP - NO VERIFICATION

⚠️ Risks: - ❌ No identity verification - System trusts whatever user types - ❌ Identity spoofing possible - User could claim another person's ID - ❌ Human error - Users may mistype their ID - ❌ No audit trail - Cannot prove who actually registered - ❌ NOT production-ready - Internal/personal use ONLY

✅ Acceptable for: - Personal projects (use Single-User Mode!) - Small team internal tools - Testing and prototyping

❌ NOT acceptable for: - Production systems - External-facing applications - Security-sensitive operations

🔧 Single-User Mode avoids this: No manual ID entry needed!

2. Multiple Feishu Bots Required 🔧 SETUP REQUIRED

This skill requires multiple Feishu Bot applications:

Bot Type Quantity Example Names
Coordinator 1 协调员
Specialists 2+ 技术专家，产品专家

📖 Setup Guide: references/feishu-bot-setup.md

⚡ Single-User Mode: Zero Configuration

Recommended for personal use!

# 1. Set environment variable
export DEPLOYMENT_MODE=single-user

# 2. Create empty mapping table (no users needed)
cat > user-mapping.json << 'EOF'
{
  "version": "1.0",
  "users": {},
  "agents": { ... }
}
EOF

# 3. Contact any Bot - auto-registers you!
# That's it! No manual User ID entry needed.

How it works: - First contact: Bot auto-registers you as userid "me" - All Bots: Automatically track your open_id - Relay: Uses hardcoded userid "me" (no queries needed) - Security: No identity spoofing risk (only you)

📖 Full guide: references/single-user-setup.md

👥 Multi-User Mode: Manual Configuration

For teams and organizations.

# 1. Set environment variable
export DEPLOYMENT_MODE=multi-user

# 2. Each user must register:
User → Bot: "你好"
Bot → User: "请告诉我您的 User ID"
User → Bot: "我的 user ID 是：zhangsan"

⚠️ Security Warning: Manual User ID entry has NO verification. Internal use only!

📖 Full guide: references/feishu-bot-setup.md

Quick Start

This skill enables multi-Agent collaboration on Feishu where: - Users contact a coordinator Bot - Coordinator relays tasks to specialist Bots - Specialists proactively message users

User → Coordinator Bot → sessions_send → Specialist Bot → User (proactive DM)
                          (userid only)    queries mapping

📋 Setup Checklist

Phase 1: Feishu Bot Configuration (~30 minutes)

  • [ ] Create Feishu Developer Account
  • [ ] Create Coordinator Bot + Specialist Bots
  • [ ] Configure Permissions
  • [ ] Configure Event Subscriptions
  • [ ] Test Each Bot

📖 Guide: references/feishu-bot-setup.md

Phase 2: Choose Deployment Mode

  • [ ] Single-User: Set DEPLOYMENT_MODE=single-user
  • [ ] Multi-User: Set DEPLOYMENT_MODE=multi-user
  • [ ] Initialize mapping table
  • [ ] Deploy mapping API

📖 Single-User Guide: references/single-user-setup.md

Phase 3: Testing (~15 minutes)

  • [ ] Test first contact (auto-register or manual)
  • [ ] Test relay flow
  • [ ] Test proactive message
  • [ ] Verify mapping table

When to Use This Skill

Use when: - ✅ Multiple Feishu Bots working together - ✅ Users contact one Bot, receive responses from different Bots - ✅ Cross-Bot user identity management needed - ✅ Specialist Bots proactively message users

Don't use for: - ❌ Single-Bot scenarios - ❌ Production without verification (multi-user) - ❌ External-facing applications

Architecture

┌─────────────────┐
│     User        │
│  (Feishu DM)    │
└────────┬────────┘
         │ 1. User contacts coordinator
         ▼
┌─────────────────┐     2. Coordinator identifies user
│  Coordinator    │        (auto or manual)
│    Agent        │
│  (orchestrator) │     3. Relay via sessions_send
└────────┬────────┘        (userid only)
         │
         ▼
┌─────────────────┐     4. Specialist queries mapping
│   Specialist    │        for own open_id
│    Agent        │
└────────┬────────┘     5. Send proactive DM
         │
         ▼
┌─────────────────────────┐
│   user-mapping.json     │
│  userid → open_id map   │
└─────────────────────────┘

Critical Concept: Feishu open_id Isolation

Each Bot has different open_id for the same user:

Same user (userid: user_demo_001):
├─ Coordinator Bot:    ou_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
├─ Tech Expert Bot:    ou_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
└─ Product Expert Bot: ou_cccccccccccccccccccccccccccccccc

You CANNOT use one Bot's open_id for another Bot!

Correct Relay Pattern ✅

// 1. Coordinator queries userid
const user = await mapping.getUserByOpenId('coordinator', userOpenId);

// 2. Send relay (userid only, NO open_id)
await sessions_send({
  agentId: 'product-expert',
  sessionKey: 'agent:product-expert:main',  // ✅ Key!
  message: `【转接任务】用户 User ID: ${user.userid}`
});

// 3. Specialist queries mapping for ITS OWN open_id
const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert'];

// 4. Send message using correct open_id
await message({
  action: 'send',
  channel: 'feishu',
  target: userOpenId,  // ✅ This Bot's open_id
  message: '您好，我是产品专家...'
});

Workflows

Workflow 1A: Single-User - Auto Registration

const DEPLOYMENT_MODE = process.env.DEPLOYMENT_MODE || 'single-user';
const SINGLE_USER_ID = 'me';

const userOpenId = getMessageContext().from;

// Auto-register on first contact
const existing = await mapping.getBotOpenId(SINGLE_USER_ID, 'coordinator');

if (!existing) {
  await mapping.updateBotOpenId(SINGLE_USER_ID, 'coordinator', userOpenId, 'Default User');

  await message({
    message: `您好！🎉 系统已自动配置完成（单用户模式）。`
  });
  return;
}

Workflow 1B: Multi-User - Manual Registration

const userOpenId = getMessageContext().from;
const user = await mapping.getUserByOpenId('coordinator', userOpenId);

if (!user) {
  // Ask for User ID
  await message({
    message: `您好！请告诉我您的 User ID（工号/用户名）。`
  });
  return;
}

await mapping.updateBotOpenId(user.userid, 'coordinator', userOpenId, user.name);

Workflow 2: Coordinator Relay

const user = await mapping.getUserByOpenId('coordinator', userOpenId);

await sessions_send({
  agentId: 'product-expert',
  sessionKey: 'agent:product-expert:main',
  message: `【转接任务】用户 User ID: ${user.userid}, 任务：${task}`
});

Workflow 3: Specialist Proactive Message

const userId = extractUserId(message);
const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert'];

if (!userOpenId) {
  await sessions_send({
    agentId: 'coordinator',
    message: `用户 ${userId} 尚未与我建立对话`
  });
  return;
}

await message({
  action: 'send',
  channel: 'feishu',
  target: userOpenId,
  message: '您好，我是产品专家...'
});

User Mapping Table

Single-User Mode (Auto-populated)

{
  "version": "1.0",
  "users": {
    "me": {
      "name": "Default User",
      "botOpenIds": {
        "coordinator": "ou_xxx",
        "tech-expert": "ou_yyy",
        "product-expert": "ou_zzz"
      }
    }
  },
  "agents": { ... }
}

Multi-User Mode (Manual registration)

{
  "version": "1.0",
  "users": {
    "zhangsan": {
      "name": "张三",
      "botOpenIds": {
        "coordinator": "ou_abc...",
        "product-expert": "ou_def..."
      }
    },
    "lisi": { ... }
  },
  "agents": { ... }
}

Configuration

Environment Variables

Variable Values Default Description
DEPLOYMENT_MODE single-user, multi-user multi-user Deployment mode
SINGLE_USER_ID Any string "me" User ID for single-user

Agent SOUL.md Template

# SOUL.md - 协调者

## 部署模式
- Mode: single-user (或 multi-user)
- User ID: "me" (single-user) 或 dynamic (multi-user)

## 配置
- Bot App ID: cli_xxx
- 映射表：/path/to/user-mapping.json

Error Handling

400 "cross app open_id"

Cause: Using wrong Bot's open_id.

Fix: Each Bot must use its own open_id from mapping.

User not found

Cause: First-time user, not registered.

Fix: Auto-register (single-user) or ask for ID (multi-user).

Testing Checklist

  • [ ] Bots created and configured
  • [ ] Deployment mode set
  • [ ] Mapping table initialized
  • [ ] First contact works
  • [ ] Relay flow works
  • [ ] Proactive message works
  • [ ] Mapping table updated correctly

Best Practices

DO ✅

  • Use agent:xxx:main for sessionKey
  • Pass only userid in relay
  • Let specialists query own open_id
  • Use mapping API (not direct file access)
  • Choose appropriate deployment mode
  • Auto-register in single-user mode

DON'T ❌

  • Pass open_id in relay
  • Use one Bot's open_id for another
  • Use feishu:direct:openid sessionKey
  • Use multi-user for production without verification
  • Share single-user Bots with others

Security Considerations

Single-User Mode ✅

  • No identity spoofing risk (only you)
  • No manual ID entry
  • Automatic registration
  • Recommended for personal use

Multi-User Mode ⚠️

  • Manual ID entry (no verification)
  • Identity spoofing possible
  • Internal use only
  • Add verification for production

Resources

scripts/

  • mapping-api.js - Unified mapping API

references/

  • single-user-setup.md - Single-user mode guide (START HERE for personal use)
  • feishu-bot-setup.md - Multi-user mode guide
  • mapping-schema.md - Schema details
  • relay-examples.md - Code examples

Version: 1.2
Last Updated: 2026-03-07
Deployment Modes: Single-User (zero-config) | Multi-User (manual)
Recommendation: Start with Single-User for testing, switch to Multi-User for teams
Status: ✅ Functional for internal/personal use | ⚠️ Not production-ready (multi-user mode)